Sending

mail.emails.send() calls POST /emails. Send with a sandbox or live key; sending-only keys are enough.

const { data, error } = await mail.emails.send({  from: 'Your product <hello@notify.yourproduct.example>',  to: ['ada@customer.example'],  cc: 'team@customer.example',  replyTo: 'support@yourproduct.example',  subject: 'Your receipt',  text: 'Thanks for your order.',  html: '<p>Thanks for your order.</p>',  headers: { 'X-Entity-Ref-ID': 'order-1042' },  tags: [{ name: 'category', value: 'receipt' }],});

The response is { id }, the message ID you’ll see in logs, webhooks and mail.emails.get(id).

mail.batch.send() calls POST /emails/batch with up to 100 messages. Letterpier checks every message first and stores the batch in one transaction, so either all of them are accepted or none is. The response lists one ID per message, in the order you sent them. An idempotencyKey covers the whole batch.

const { data, error } = await mail.batch.send(  [    {      from: 'Your product <hello@notify.yourproduct.example>',      to: 'ada@customer.example',      subject: 'Your weekly summary',      text: 'Here is what happened this week.',    },    {      from: 'Your product <hello@notify.yourproduct.example>',      to: 'grace@customer.example',      subject: 'Your weekly summary',      text: 'Here is what happened this week.',    },  ],  { idempotencyKey: 'weekly-summary/2026-40' },);// data?.data holds one { id } per message, in order.

Set scheduledAt to an ISO 8601 time with an offset, such as 2026-10-02T09:00:00+02:00, in the future and at most 30 days ahead. The message waits as Scheduled until then.

// An ISO 8601 time with an offset, at most 30 days ahead.const { data } = await mail.emails.send({  from: 'Your product <hello@notify.yourproduct.example>',  to: 'ada@customer.example',  subject: 'Your trial ends tomorrow',  text: 'Your trial ends tomorrow at noon.',  scheduledAt: '2026-10-02T09:00:00+02:00',});// Move it (full-access key): only while it's still queued or scheduled.await mail.emails.update({  id: data!.id,  scheduledAt: '2026-10-03T09:00:00+02:00',});// Or cancel it (full-access key).await mail.emails.cancel(data!.id);

• Reschedule with mail.emails.update() (PATCH /emails/:id), within the same 30-day window.
• Cancel with mail.emails.cancel() (POST /emails/:id/cancel). The message becomes Cancelled.
• Both need a full-access key (a sending-only key gets 403 restricted_api_key) and work only while the message is still queued or scheduled; otherwise the answer is 409.

Pass idempotencyKey (the Idempotency-Key header, 1 to 256 characters) whenever you might send the same request twice, for example after a timeout.

• A key lasts 24 hours and is scoped to the project, the environment and the operation (send or batch). Every key of the project in that environment shares it.
• The same key with the same request returns the first response. No second message is created.
• The same key with a different request is refused with 409 invalid_idempotent_request.

Each attachment has content as base64 text, a filename and, optionally, contentType. A message can carry up to 20 attachments, and a request up to about 10 MB of them, decoded.

import { readFile } from 'node:fs/promises';const invoice = await readFile('invoice-1042.pdf');await mail.emails.send({  from: 'Your product <billing@notify.yourproduct.example>',  to: 'ada@customer.example',  subject: 'Invoice 1042',  text: 'Your invoice is attached.',  attachments: [    {      filename: 'invoice-1042.pdf',      content: invoice.toString('base64'), // base64 text, not a Buffer      contentType: 'application/pdf',    },  ],});

Every limit and window

The live checks run again just before the worker hands a message to Postal. If one fails then, the message is Held (or Suppressed) and your webhook receives email.failed.

A 200 means Letterpier stored the message and queued it. From there, a live message moves on by itself:

1. Queued (or Scheduled): waiting for the worker.
2. Submitting: the worker hands it to Postal.
3. Sent: Postal accepted it and is delivering it.
4. Delivered: the recipient’s mail server accepted it. Or Delayed, Bounced or Failed.

All statuses and the webhook for each

Errors are JSON with the HTTP status, a name and a readable message. The SDK returns them as error with data: null; it doesn’t throw.

{  "statusCode": 409,  "name": "invalid_idempotent_request",  "message": "This idempotency key was already used with a different request."}