Sign in to fill these examples with your own keys. Sign in Start free trial

Send emails with Dart

Install the Dart SDK from GitHub and call emails.send.

What you'll build

A Dart program that sends a receipt email with the postshiba package and prints the queued message.

Before you start

  • An API key with Send only access. Full access also works. See Create an API key. Support keys cannot send.
  • A verified sending domain. See Add and verify a domain. from must be an address on it.
  • A cluster that is ready to send (sending_ready is true). See Clusters.
  • Dart 3 or later.

Keep the API key on a server. Do not ship it inside a client app.

Install

The package is on GitHub, not pub.dev. Add it to pubspec.yaml, then run dart pub get.

pubspec.yaml
1dependencies: 2 postshiba: 3 git: 4 url: https://github.com/postshiba/postshiba-dart.git

Send your first email

Pass your API key to PostShiba, then await emails.send with a map. teamId is only needed for team-scoped calls such as listing clusters, and those calls need a Full access key that stays out of your deployed app. It is on the API keys page.

send.dart
1import 'package:postshiba/postshiba.dart'; 2 3Future<void> main() async { 4 final client = PostShiba("YOUR_API_KEY", teamId: "KjkAJW"); 5 6 final sent = await client.emails.send({ 7 "from": "hello@mail.example.com", 8 "to": ["you@example.com"], 9 "reply_to": "support@example.com", 10 "subject": "Your receipt", 11 "text": "Thanks for your order.", 12 "html": "<p>Thanks for your order.</p>", 13 "unique_args": {"order_id": "ord_123"}, 14 }); 15 16 print(sent); 17}

Run it with dart run send.dart. emails.send returns the JSON body of the 201 response as a Map<String, dynamic>. The message then shows under Events in the dashboard.

response.json
1{ 2 "queued": true, 3 "message_id": "abc@capsule.test", 4 "from": "hello@mail.example.com", 5 "to": ["you@example.com"], 6 "subject": "Your receipt", 7 "unique_args": {"order_id": "ord_123"} 8}

Pin a cluster

Without a pin, PostShiba uses your first cluster that is ready to send. Pass clusterId to choose one.

pin.dart
1await client.emails.send(message, clusterId: "NmQpXr");

Attachments and templates

Attach a file

Add attachments with filename, content_type, and base64 content. Up to 10 files, 18 MB in total. See Attachments for allowed types.

attachment.dart
1import 'dart:convert'; 2import 'dart:io'; 3 4final pdf = base64Encode(await File("invoice.pdf").readAsBytes()); 5 6await client.emails.send({ 7 "from": "hello@mail.example.com", 8 "to": ["you@example.com"], 9 "subject": "Your invoice", 10 "text": "Your invoice is attached.", 11 "attachments": [ 12 {"filename": "invoice.pdf", "content_type": "application/pdf", "content": pdf}, 13 ], 14});

Send a published template

Pass template with the alias or public id and its variables. Leave out html and text.

template.dart
1await client.emails.send({ 2 "from": "hello@mail.example.com", 3 "to": ["you@example.com"], 4 "template": { 5 "id": "welcome", 6 "variables": {"name": "Ada"}, 7 }, 8});

Keep the key safe

Use a Send only key on your server. It can send email and call GET /api/v1/users/me. Every other request returns 403 forbidden.

If this key leaks Send only Full access
Send mail from your verified domains Yes Yes
Read events, recipients, templates, and sent messages No Yes
See SMTP passwords and webhook secrets No Yes
Change clusters, domains, credentials, webhooks, and suppressions No Yes
  • Never embed a key, even a Send only key, in a Flutter, mobile, or web app. Anyone can pull it out of the app bundle and send mail from your domains. Have the app call your own backend, and send from there.
  • Keep Full access keys for setup scripts, the CLI, and MCP. Don't deploy one with your server.
  • Read the key with Platform.environment["POSTSHIBA_API_KEY"] from dart:io instead of a string in your code. Don't commit it, log it, or put it in a URL.
  • Create one key per app and environment. If a key leaks, delete it on API keys and create a new one. Deleting stops it straight away.

Troubleshooting

A response outside 2xx throws ApiException with error, field, message, and statusCode.

errors.dart
1try { 2 await client.emails.send(message); 3} on ApiException catch (e) { 4 print("${e.statusCode} ${e.error} ${e.field} ${e.message}"); 5 rethrow; 6}
Status error What to do
401 Invalid token or no user signed in The API key is missing, mistyped, or deleted. Copy it again from API keys.
403 forbidden Support keys cannot send. A Send only key gets this on any call other than sending.
403 domain_unverified from is not on a verified domain.
403 kyc_required Your team is pending production approval. Until then, send only to team members, live inbox addresses, and inbox forward-to addresses.
422 invalid field names the problem, such as a missing to, an unpublished template, or a rejected attachment.
429 throttled The cluster hit its hourly throttle or 24-hour cap. The client does not retry, and retrying right away hits the same cap. See What happens at your cap.
429 rate_limited More than 300 send requests in one minute on one API key. Slow down.

Every other status is on Errors.

Next steps