Send an email

Request

import { Posthaste } from '@posthaste/sdk'

const posthaste = new Posthaste({ apiKey: process.env.POSTHASTE_KEY })

const result = await posthaste.emails.send({
  from: 'Acme Billing <[email protected]>',
  to: '[email protected]',
  subject: 'Invoice 2026-114',
  text: 'Your invoice is attached to your account.',
  html: '<p>Your invoice is attached to your account.</p>',
  replyTo: '[email protected]',
  headers: { 'X-Acme-Invoice': '2026-114' },
  listUnsubscribe: '<https://yourdomain.com/u/abc123>, <mailto:[email protected]>',
  // A BODY field, and the SDK puts it there. The Idempotency-Key header is
  // never read by any endpoint.
  idempotencyKey: 'invoice-2026-114',
})

result.id        // 'msg_AZLm3kQ8T2Sf9pXbNc7HrQ'
result.status    // 'queued'    (202) | 'duplicate' (200)
result.duplicate // false       — both are success; this says which happened

if (result.duplicate) {
  // Nothing was sent. result.id is the message we accepted the first time.
}

List-Unsubscribe is worth setting

Gmail and Yahoo have required a one-click unsubscribe header on bulk mail since 2024, and both weigh its presence when deciding where mail lands. Transactional mail is not bulk mail, but the header is still the cheapest deliverability win available on any message a recipient might reasonably want to stop receiving — notifications, digests, receipts for a subscription.

Two forms are recognised by mail clients, and supplying both is standard: <https://…>, <mailto:…>. Because we also send List-Unsubscribe-Post, the HTTPS URL must accept a POST and unsubscribe the recipient without asking them to confirm — that is what “one-click” means, and a link that lands on a confirmation page fails the requirement it was added for.

Response

Refusals

The cheap structural checks run before any query, suppression is checked before anything is written, and the sending cap is checked last — so a message refused for any other reason never consumes quota.

import { isPosthasteError } from '@posthaste/sdk'

try {
  await posthaste.emails.send({ from, to, text, idempotencyKey })
} catch (err) {
  if (!isPosthasteError(err)) throw err

  err.status  // 422
  err.type    // 'domain_not_verified'
  err.message // 'yourdomain.com is not verified. Publish its DNS records…'

  // fields[] is present on SOME 400s and absent on others — the SDK leaves it
  // undefined rather than inventing an empty array, so always check.
  for (const field of err.fields ?? []) {
    console.error(field.path || '(whole body)', field.message)
  }
}

Nothing over a cap is queued and delivered later. A refused message was never accepted, is never billed, and never appears in your usage figures.

Header injection is rejected, not sanitised

A carriage return or newline anywhere in an address, subject, custom header name, custom header value or listUnsubscribe returns 400. It is checked twice — once at the API boundary and again in the composer — so a path that skipped the first check still cannot produce a malformed message.

Silently stripping the characters instead would be worse than refusing: a crafted subject could append a Bcc: header that nobody, including you, would ever see in the record.