Send email, and see exactly what happened to it.

Quickstart

Two things stand between you and a delivered email: one DNS record, and one request.

const res = await fetch('https://api.posthastemail.dev/v1/emails', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.POSTHASTE_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Reset your password',
    text: 'Click the link to reset your password.',
  }),
})

// 202 { id: 'msg_AaBbCcDdEeFfGgHh4Kq', status: 'queued' }

Authentication

Every request carries an API key as a bearer token. Keys are shown once when created and stored only as a hash — if you lose one, nobody can recover it.

authorization: Bearer ph_live_8Fk2mQx7Rd4pLw9…

Scopes

Keys grant only what they list. A missing scope is denied, so an endpoint added later is closed to your existing keys rather than silently reachable by all of them.

Verify a domain

We sign your mail as your domain, so you publish one record proving we are allowed to. Sending from an unverified domain is refused outright rather than queued and failed later.

Send an email

Idempotency

Send the same idempotencyKey twice and the second call returns 200 with the original message id, rather than 202 and a second delivery. This is the safe way to retry a request whose response you never saw.

The waybill

A waybill is the complete record of one message: every event it passed through, and the verbatim SMTP conversation with the receiving server. It is append-only and hash-linked, so you can verify independently that nothing was rewritten afterwards.

Each event carries hash and prevHash. The chain is per account rather than per message, so a message’s first event links to whatever preceded it in your account’s chain.

Webhooks

Rather than polling, register an endpoint and we post events to it as they happen. Every delivery is signed and timestamped.

Verifying a signature

The timestamp is signed with the body. Signing the body alone would be replayable forever — anyone who captured one valid request could resend it indefinitely and it would still verify.

import { verifyWebhook } from 'posthaste'

app.post('/hooks/posthaste', (req, res) => {
  const result = verifyWebhook(
    req.rawBody,
    req.headers['posthaste-signature'],
    process.env.POSTHASTE_WEBHOOK_SECRET,
  )

  if (!result.valid) {
    // 'signature_mismatch' | 'timestamp_too_old' | …
    return res.status(400).send(result.reason)
  }

  return res.sendStatus(200)
})

Retries

Any non-2xx is retried on a schedule of 10s, 1m, 5m, 30m, 2h, 6h and 12h. Two exceptions: 410 Gone and 404 stop immediately, because the endpoint is telling us it no longer exists. An endpoint failing for 24 hours with no successes is disabled automatically.

Suppressions

An address that hard bounces or files a complaint is suppressed immediately and will not be sent to again by anyone. Attempting to send returns 422 with the reason.

Errors

Errors return a machine-readable type and a message written for a human reading a log at 2am.

Limits and warmup

New sending IPs have no reputation, and volume that appears from nothing looks exactly like a compromised host. So capacity rises on a schedule rather than being available immediately.

Your monthly allowance

Separately from the daily ramp, each plan includes a number of messages a month — 5,000 on Free, 100,000 on Starter, 300,000 on Growth, 1,000,000 on Scale. It is counted per calendar month in UTC, and it counts accepted messages only: a send we refuse was never attempted, so it is never billed and never counted.

Exceeding it returns 429 with "type": "monthly_limit_reached" and a Retry-After pointing at the start of next month rather than at midnight. Moving to a larger plan lifts the ceiling immediately — there is nothing to wait for.

GET /v1/usage returns the current period’s totals with the daily series behind them, so you can see which days produced a number rather than taking it on trust. Those counters are derived from the delivery record itself, not tallied separately, which is why they cannot drift from what actually happened.

Your account’s daily cap

The schedule above is the shared sending IP. Your own account also has a daily cap that starts at 200 messages and climbs one step at a time: 200, 500, 1,000, 2,500, 5,000, 10,000, 25,000, 50,000, 100,000, 250,000.

It moves once a day, based only on the day before. You go up a step after a day where you used at least 80% of your current cap with a complaint rate at or under 0.1% and a bounce rate at or under 5%. You go down a step after a day where complaints passed 0.3% or bounces passed 10%. Never more than one step either way, and an idle day moves nothing — capacity is earned with real volume, not with time.

Sending past the cap returns 429 with a Retry-After header pointing at the reset, which is midnight UTC. The error body carries the limit and how many you have sentToday. Nothing is queued and delivered later — a refused message was never accepted.

You do not have to wait for a 429 to find out where you stand: GET /v1/me returns sending.dailyLimit, sending.sentToday and sending.remainingToday.