[bjarn]

Stacked on #39 — merge that first.

What changed

Non-breaking; suggested bump: minor.

• New exported type BatchEmailMessage: an EmailMessage with an optional per-email idempotency_key. emails.sendBatch() now accepts (BatchEmailMessage | EmailBuilder)[]. EmailMessage[] still works as before.
• Each key goes in its own batch item as idempotency_key. It is separate from the request-level idempotencyKey option, which still sends the Idempotency-Key header.
• If an email with the same key and content was accepted in the last 24 hours, the API returns the original result and does not send it again. A retried batch therefore sends only the emails that were not accepted yet.
• Builders get a key by spreading their wire format: { ...builder.build(), idempotency_key }. No builder setter was added, so builder.send() and emails.send() stay unchanged and EmailMessage (the single-send type) does not get the field.
• The API validates the keys (1-255 characters, unique within a batch, 409 Conflict when a key is reused with different content). The SDK adds no client-side checks.
• Docblock and README: on a mid-batch failure, error.details.accepted lists the emails that were already accepted ({ index, message_id }).

Usage

await lettermint.emails.sendBatch(
  [
    { ...invoice, idempotency_key: `invoice-${invoice.id}` },
    { ...welcome.to('john@example.com').build(), idempotency_key: 'welcome-john' },
  ],
  { idempotencyKey: 'batch-2026-10-18' } // optional, for the request as a whole
);

Checks

Run locally on Node 26.5.0:

• npm run lint: passed (33 files, no fixes)
• npm run type-check: passed
• npm run generate:check: generated files up to date (with the generator), and the header check passed without it
• npm run test:coverage: 319 passed, 8 suites
• npm run build: CJS, ESM and DTS builds succeeded
• npm run test:smoke: ESM import, CJS require and type declarations ok

Not run locally

• The Node 20, 22 and 24 CI matrix. Only Node 26 was run locally.

Suggested release tag

v3.2.0 if released together with #39, otherwise the next minor after it.

🤖 Generated with Claude Code