One request, one email, one stamp.

Send your first email

Create a key in your account, keep it on your server, and send it as a Bearer token. Keys start with fs_live_ and are shown once.

curl https://flatstamp.com/api/v1/send \
  -H "Authorization: Bearer $FLATSTAMP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Alice Books <hello@alicebooks.com>",
    "to": "reader@example.com",
    "subject": "Your receipt",
    "html": "<p>Thanks for your order!</p>",
    "text": "Thanks for your order!"
  }'

Or from Node, Bun or Deno:

const res = await fetch("https://flatstamp.com/api/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATSTAMP_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: { email: "hello@alicebooks.com", name: "Alice Books" },
    to: "reader@example.com",
    subject: "Your receipt",
    text: "Thanks for your order!",
  }),
});
const data = await res.json(); // { id, status: "queued" } or { error: { code, message } }

Fields

from

required"Name <you@yourdomain.com>", an address, or { email, name }. Must be on a domain you've verified.

to

requiredOne address. One stamp sends to one person, so send once per recipient.

subject

requiredOne line, up to 200 characters.

html / text

one requiredSend both when you can. HTML up to 500,000 characters, text up to 200,000.

reply_to

optionalWhere replies go, if not the from address.

kind

optional"transactional" (default: receipts, resets, alerts) or "marketing" (adds your postal address, an unsubscribe link and tracking).

Responses

Success returns { "id": "…", "status": "queued" }. Errors return { "error": { "code", "message" } }.

202 queued

Accepted. One stamp is set aside and charged when the email goes out.

400 invalid_request

Something in the body is missing or malformed. The message says what.

401 unauthorized

Missing, unknown or revoked key.

402 no_stamps

Out of stamps. Nothing was queued or charged.

403 domain_unverified

The from address isn't on one of your verified domains.

403 account_inactive

The account is paused.

500 server_error

Our fault. Nothing was sent or charged; it's safe to retry.

How stamps work with the API

• Queuing an email sets one stamp aside. It's charged when we hand the email to our mail servers.
• If we can't send it (a blocked address, a failure on our side), the stamp comes back.
• Hard bounces and spam complaints block that address for good, so you never pay to mail it again.
• Marketing email must carry your postal address; set it in your account before sending with kind "marketing".

Flatstamp is opening as an invite-only beta. API keys come with your account.