dart_resend 2.0.0

A production-ready Dart SDK for the complete Resend email API.

dart_resend

A production-ready, community-maintained Dart SDK for the complete Resend API.

The public surface tracks the official Resend API reference and its canonical OpenAPI specification.

dart_resend 2.0 provides typed request and response models, cursor pagination, request metadata, predictable exceptions, local validation, dependency-injected HTTP transport, and first-class support for every current Resend resource.

Developed with 💙 and maintained by coderave

Important notes

• Keep API keys on a trusted server. Never embed a Resend API key in a web, Flutter, mobile, desktop, or other distributed client. Route those requests through your own authenticated backend.
• 2.0.0 is an intentional breaking redesign. The singleton, ResendClient, ResendResult, legacy feature clients, and legacy response classes were removed. See the migration guide.
• Audiences were removed. Resend's current API uses global Contacts and Segments. The package no longer exposes the retired Audiences resource.
• Suppressions are private beta. The API is implemented, but calls only work for Resend teams with access to the gated feature.

Install

dart pub add dart_resend

The package requires Dart 3.8 or newer.

Quick start

import 'package:dart_resend/dart_resend.dart';

Future<void> sendEmail(String apiKey) async {
  final Resend resend = Resend(apiKey: apiKey);
  try {
    final ResendResponse<ResendId> response = await resend.emails.send(
      SendEmailRequest.raw(
        from: 'Acme <[e-mail]>',
        to: <String>['[e-mail]'],
        subject: 'Hello from dart_resend',
        html: '<strong>It works!</strong>',
        text: 'It works!',
      ),
    );
    print(response.data.id);
  } finally {
    resend.close();
  }
}

Run the complete quick start with an environment variable:

RESEND_API_KEY=re_... dart run example/main.dart

See the runnable example.

Client lifecycle

Create one Resend instance per application or service and reuse it. Calling close() releases the internally owned HTTP client and is safe to do more than once. Calls made after closing fail with StateError.

When an http.Client is injected, it remains caller-owned by default. Set closeClient: true if Resend.close() should close the injected client too. The constructor also accepts a request timeout, defaultHeaders, and custom baseUri for tests or compatible gateways. See useConfiguredClient.

OAuth registration and token endpoints do not require an API key. Use Resend.unauthenticated() for those calls and an authenticated Resend client for team resources and OAuth grant management.

Responses, pagination, and errors

Every network method returns Future<ResendResponse<T>>. The response contains the decoded data, HTTP statusCode, immutable lowercase headers, Resend requestId, and parsed rateLimit metadata. Response models also retain their complete immutable payload in json, so newly added server fields remain available before the SDK adds typed getters.

List operations accept PaginationOptions(limit:, after:, before:) and return ResendPage<T>, whose data and hasMore fields drive cursor iteration. after and before are mutually exclusive; limits must be between 1 and 100. See cursor iteration and response metadata.

Failures are thrown as typed exceptions:

• ResendApiException for non-2xx API responses, including the status, error name, request ID, headers, parsed details, and raw body.
• ResendTimeoutException when the configured timeout expires.
• ResendNetworkException for other transport failures.
• ResendDecodeException when a successful response cannot be decoded.
• ArgumentError, RangeError, or StateError for invalid local usage.

See the complete error-handling example.

Complete feature and example index

Every public Resend operation is demonstrated below. The linked files are part of the analyzed package examples and use only the public library entrypoint.

Emails

• emails.send with raw HTML/text, recipients, headers, tags, inline bytes, Base64 and remote attachments, topic, and idempotency
• emails.send with a published template and variables
• emails.send with scheduled delivery
• emails.sendBatch with raw and template emails, permissive validation, tags, and idempotency
• emails.list
• emails.retrieve
• emails.update to reschedule
• emails.cancel
• emails.listSentAttachments
• emails.retrieveSentAttachment
• emails.listReceived
• emails.retrieveReceived with inline-image format control
• emails.listReceivedAttachments
• emails.retrieveReceivedAttachment

Batch sends support tags but not attachments or scheduled_at. A batch may contain 1–100 emails and can use strict all-or-nothing or permissive per-item validation.

Domains

• domains.create with region, TLS, tracking, return path, and capabilities
• domains.list
• domains.retrieve and DNS records
• domains.update
• domains.verify
• domains.delete
• domains.claim
• domains.retrieveClaim
• domains.verifyClaim

Domain DNS models preserve unknown record kinds and types for forward compatibility. A configured tracking subdomain can currently be replaced and reverified, but not removed.

API keys

• apiKeys.create with sending-only and domain-restricted permissions
• apiKeys.list
• apiKeys.delete

The token returned by apiKeys.create is shown only once; store it in a secret manager and never log it.

Broadcasts

• broadcasts.create as a draft
• broadcasts.create and schedule immediately
• broadcasts.list
• broadcasts.retrieve
• broadcasts.update, including clearing a topic
• broadcasts.send now or later
• broadcasts.delete or cancel

Templates

• templates.create with string, number, boolean, object, and list variables
• templates.list
• templates.retrieve by ID or alias
• templates.update
• templates.publish
• templates.duplicate
• templates.delete
• Send a published template

Contacts and imports

• contacts.create with custom properties, segments, and topics
• contacts.list
• contacts.list filtered by segment
• contacts.retrieve by ID or email
• contacts.update, clear names, and remove property values
• contacts.delete by ID or email
• contacts.listSegments
• contacts.addToSegment
• contacts.removeFromSegment
• contacts.listTopics
• contacts.updateTopics with opt-in and opt-out values
• contacts.imports.create with CSV mapping, conflict behavior, segments, and topics
• contacts.imports.list with status filtering
• contacts.imports.retrieve and row counts

Contacts are global. Use segments for grouping and topics for granular contact preferences; use unsubscribed for the global broadcast preference.

Segments

• segments.create
• segments.list
• segments.retrieve
• segments.listContacts
• segments.delete

Topics

• topics.create with default subscription and public/private visibility
• topics.list with cursor pagination
• topics.retrieve
• topics.update, including visibility
• topics.delete

Contact properties

• contactProperties.create with typed fallback values
• contactProperties.list
• contactProperties.retrieve
• contactProperties.update or clear a fallback
• contactProperties.delete

Webhooks

• webhooks.create and every documented event type
• webhooks.list
• webhooks.retrieve and its signing secret
• webhooks.update
• webhooks.delete
• Verify the raw payload and svix-* headers locally

Never parse and re-encode a webhook body before verification. Verification uses the raw request body and throws ResendWebhookVerificationException for an invalid signature, timestamp, or payload.

API logs

• logs.list
• logs.retrieve with request and response bodies

Automations and runs

• Every condition operator plus all and any groups
• Forward-compatible custom automation steps
• automations.create with trigger, wait, condition, email, delay, contact update, segment, contact-delete, variables, and every branch type
• automations.list with status filtering
• automations.retrieve and its graph
• automations.update
• automations.stop
• automations.delete
• automations.runs.list with status filtering
• automations.runs.retrieve with step diagnostics

Automation graph builders validate the trigger, unique keys, endpoints, reachability, connection branches, and duplicate connections before sending.

Custom events

• events.create with every schema type
• events.list
• events.retrieve by ID or name
• events.update or clear the schema
• events.delete by ID or name
• events.send to a contact ID
• events.send to an email address

Suppressions (private beta)

These calls require private-beta access on the authenticated Resend team:

• suppressions.add
• suppressions.addBatch
• suppressions.retrieve by ID or email
• suppressions.list with origin filtering
• suppressions.remove
• suppressions.removeBatch by email
• suppressions.removeBatch by ID

OAuth 2.1 and PKCE

• Resend.unauthenticated and oauth.register
• OAuthPkcePair.generate and oauth.authorizationUri
• OAuthPkcePair.fromVerifier
• oauth.exchangeCode
• oauth.refresh
• oauth.revokeToken
• Create a Resend client from an OAuth access token
• oauth.listGrants with team authentication
• oauth.revokeGrant with team authentication

Use a cryptographically random state, bind it to the browser session, and store the PKCE verifier securely until the callback. OAuth access and refresh tokens are secrets and must remain server-side. Authorization URLs default to https://api.resend.com/oauth/authorize; override authorizationBaseUri only for an intentional compatible service or test environment.

Version 2 migration

Version 2 deliberately does not include compatibility shims for the old API. Read MIGRATION.md for old-to-new call mappings, the new exception model, and the Audiences-to-Segments migration.

Contributing

See CONTRIBUTING.md for package development, tests, coverage, documentation, and pull-request requirements.