The postie handbook

1. Sign up, add your domain and set its DNS records. 2. Create an API key. 3. Send your first email:

const res = await fetch("https://api.postie.sh/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Shop <orders@yourshop.com>",
    to: "customer@example.com",
    subject: "Order #1042 confirmed",
    html: "<p>Thanks for your order!</p>",
    tags: [{ name: "kind", value: "order_confirmation" }],
  }),
});

const { id } = await res.json();

Or from a terminal:

curl -X POST https://api.postie.sh/emails \
  -H "Authorization: Bearer po_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from":"orders@yourshop.com","to":"customer@example.com","subject":"Hi","text":"Hello"}'

A successful send returns { "id": "…" }. Use that ID with GET /emails/:id to check its status.

Every request needs an Authorization: Bearer po_… header. Keys are shown once when you create them, and only a SHA-256 hash is stored.

POST /emails accepts from, to, subject, html and/or text, cc, bcc, reply_to, headers, attachments (base64 content or a path URL), tags and scheduled_at. Batch sends don’t support attachments or scheduling.

Send an Idempotency-Key header, e.g. your order ID. Retrying with the same key returns the original email ID instead of sending again. In a batch, each email gets key:index.

await fetch("https://api.postie.sh/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EMAIL_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}`,
  },
  body: JSON.stringify(email),
});

Set scheduled_at to an ISO 8601 date or plain English such as in 1 hour, in 30 minutes or in 2 days. It can be up to 30 days ahead. Reschedule with PATCH /emails/:id or cancel with POST /emails/:id/cancel.

When you add a domain, postie sets it up for sending and returns the records to add at your DNS provider. Verified domains also cover their subdomains.

The DKIM records sign your mail. The bounce. MX and TXT records set a custom MAIL FROM domain, so bounces come back to us and SPF aligns. Pending domains are checked every 15 minutes, or right away with POST /domains/:id/verify.

Add endpoints in the dashboard and choose which events to receive. Each delivery is a JSON { type, created_at, data } body.

Every delivery carries three headers: webhook-id, webhook-timestamp (unix seconds) and webhook-signature. The signature is v1, followed by a base64 HMAC-SHA256 of ${id}.${timestamp}.${body}, keyed with your signing secret base64-decoded after the whsec_ prefix. Reject requests older than five minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(req: Request, body: string, secret: string) {
  const id = req.headers.get("webhook-id") ?? "";
  const ts = req.headers.get("webhook-timestamp") ?? "";
  const sig = req.headers.get("webhook-signature") ?? "";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const want = createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest("base64");
  return sig.split(" ").some((s) => {
    const got = s.replace(/^v1,/, "");
    return got.length === want.length && timingSafeEqual(Buffer.from(got), Buffer.from(want));
  });
}

Failed deliveries (anything other than a 2xx) retry six times over about 17 hours. Every delivery, its response and a replay button are in the dashboard.

Errors always return the same shape, with a stable name you can switch on:

{ "statusCode": 422, "message": "Missing `to` field.", "name": "validation_error" }

Monthly volume, domains and webhook endpoints depend on your plan. See pricing for every plan's limits.

Addresses that hard bounce or complain are suppressed automatically. Sending to them returns an ID with status suppressed, and nothing is sent.