Plunk REST Client

Email remains one of the most effective channels for communicating with users, whether you're sending transactional messages, marketing campaigns, or important notifications. For Dart and Flutter developers looking to integrate robust email capabilities into their applications, this Plunk library offers a comprehensive solution that's easy to use and packed with features.

Plunk is a modern email platform designed specifically for SaaS applications. It provides powerful tools for sending transactional emails, managing contacts, and running email marketing campaigns. The plunk package is a Dart client that makes it easy to integrate with the Plunk API in your Dart or Flutter applications.

The plunk package is a REST client for the Plunk email platform for SaaS. This client is based on the published Plunk API.

The Plunk REST Client is maintained by DartFoundry where it is used by the Hypermodern AI platform and products to send emails on behalf of partners and to customers.

To learn more about this library, read our article Introducing the Plunk Email Library for Dart Developers.

Important

This library has been updated to support the latest Plunk API and as a result has BREAKING CHANGES. Please refer to the CHANGELOG for a list of changes.

Features

• Contact Management: Create, retrieve, update, and delete contacts
• Email Sending: Send transactional emails with customizable headers and content
• Event Tracking: Track user events and activities
• Campaign Management: Create, manage, and send email campaigns
• Subscription Control: Manage subscription preferences for contacts

Getting Started

Add the Plunk client package to your pubspec.yaml:

  dependencies:
    plunk: ^2.1.0

Then run:

dart pub get

Quick Start

Initialize the client with your API key and start using Plunk's features:

import 'package:plunk/plunk.dart';

void main() async {
  final plunk = Plunk(apiKey: 'YOUR_API_KEY');

  // Send a transactional email
  final response = await plunk.sendEmail(
    to: ['[email protected]'],
    subject: 'Welcome to Our Service',
    body: '<h1>Welcome!</h1><p>Thank you for signing up.</p>',
    from: '[email protected]',
    name: 'Your Company',
  );

  print('Email sent: ${response.success}');
}

Usage Examples

Contact Management

// Create a new contact
final contact = await plunk.createContact(
  email: '[email protected]',
  subscribed: true,
  data: {
    'firstName': 'John',
    'lastName': 'Doe',
    'plan': 'premium',
  },
);

// Get a contact by ID
final retrievedContact = await plunk.getContact(id: contact.id!);

// Update a contact
await plunk.updateContact(
  id: contact.id,
  subscribed: true,
  data: {
    'plan': 'enterprise',
    'lastLogin': DateTime.now().toIso8601String(),
  },
);

// Delete a contact
await plunk.deleteContact(id: contact.id!);

Subscription Management

// Subscribe a contact
await plunk.subscribeContact(email: '[email protected]');

// Unsubscribe a contact
await plunk.unsubscribeContact(email: '[email protected]');

Event Tracking

// Track a user event
await plunk.trackEvent(
  email: '[email protected]',
  event: 'completed_purchase',
  data: {
    'product': 'Premium Plan',
    'amount': 99.99,
    'currency': 'USD',
  },
);

Email Campaigns

// Create a campaign
final campaign = await plunk.createCampaign(
  subject: 'New Feature Announcement',
  body: '<h1>Exciting News!</h1><p>We just launched a new feature...</p>',
  recipients: ['[email protected]', '[email protected]'],
  style: CampaignStyle.html,
);

// Send the campaign
await plunk.sendCampaign(
  id: campaign.id!,
  live: true,
);

API Reference

Contact Methods

Method	Description
getContact()	Retrieves a specific contact by ID
getAllContacts()	Gets all contacts in your Plunk account
getContactCount()	Gets the total number of contacts
createContact()	Creates a new contact
updateContact()	Updates an existing contact
deleteContact()	Deletes a contact
subscribeContact()	Sets a contact's subscription status to subscribed
unsubscribeContact()	Sets a contact's subscription status to unsubscribed

Email Methods

Method	Description
sendEmail()	Sends a transactional email to one or more recipients
trackEvent()	Tracks an event for a specific contact

Campaign Methods

Method	Description
createCampaign()	Creates a new email campaign
updateCampaign()	Updates an existing campaign
deleteCampaign()	Deletes a campaign
sendCampaign()	Sends a campaign to its recipients

Error Handling

The library provides specific exception types to handle different error scenarios:

try {
  await plunk.createContact(/* ... */);
} catch (e) {
  if (e is PlunkInvalidRequestException) {
    print('Invalid request: ${e.message}');
  } else if (e is PlunkAuthorizationException) {
    print('Authorization error: ${e.message}');
  } else if (e is PlunkQuotaException) {
    print('Quota exceeded: ${e.message}');
  } else if (e is PlunkUnknownException) {
    print('Unknown error: ${e.message}');
  } else if (e is PlunkConflictException) {
    print('Unknown error: ${e.message}');  }
}

Configuration

The Plunk client can be configured with several options:

final plunk = Plunk(
  apiKey: 'YOUR_API_KEY',
  apiVersion: 'v1',
  baseUrl: 'https://api.useplunk.com',
  timeout: Duration(seconds: 60),
);

Requirements

• Dart SDK 3.0.0 or higher

Learn More

• Plunk Documentation
• Plunk API Reference

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Copyright

This package is Copyright ⓒ 2025 Dom Jocubeit. All rights reserved.