Send Email

Send transactional emails immediately or schedule them for later delivery. Supports Idempotency-Key for safe retries and "Display Name <email@domain>" sender format.

Idempotency

Pass an Idempotency-Key header (any unique string up to 255 chars — UUIDs work great) to make your send requests idempotent. The response is cached for 24 hours, so retrying a request with the same key returns the original result without sending again. Critical for any client retrying after network errors.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Sender format

The from field accepts both bare addresses and RFC 5322 "Display Name <email>" format:

"hello@yourdomain.com"
"Posthawk Team <hello@yourdomain.com>" ← recommended for branded transactional mail
"\"Posthawk, Inc.\" <hello@yourdomain.com>" ← quote display names containing commas or special chars

Posthawk extracts the actual email for SES routing and SES domain verification, but keeps the display name intact in the From: header that the recipient sees.

POST/v1/send

Send an email immediately, or schedule it for future delivery by including scheduledFor. Supports `Idempotency-Key` header for safe retries (response cached 24h).

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Body

fromstringrequired

Sender email address. Accepts bare "hello@domain.com" or "Display Name <hello@domain.com>" RFC 5322 format. Domain must be verified for sending.

tostring[]required

Array of recipient email addresses

ccstring[]optional

Array of CC email addresses

bccstring[]optional

Array of BCC email addresses

replyTostringoptional

Reply-to email address

subjectstringrequired

Email subject line. Not required if templateId is provided.

htmlstringoptional

HTML email body. Either html or text is required (unless templateId is provided).

textstringoptional

Plain text email body

templateIdstringoptional

UUID of an email template. Overrides subject/html/text with template content.

variablesRecord<string, string>optional

Key-value pairs for template variable substitution

scheduledForstringoptional

ISO 8601 datetime for scheduled delivery. Must be in the future, max 30 days ahead.

timezonestringoptional

Timezone for the scheduled time (e.g., "America/New_York")

headersRecord<string, string>optional

Custom email headers (e.g. List-Unsubscribe for RFC 8058 one-click unsubscribe). Forbidden headers: from, to, cc, bcc, subject, date, message-id, mime-version, content-type, content-transfer-encoding.

POST /v1/send

curl -X POST https://your-posthawk-instance.com/v1/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Welcome to Posthawk",
    "html": "<h1>Hello!</h1><p>Welcome aboard.</p>",
    "headers": {
      "List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=abc123>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
    }
  }'

Response

{
  "success": true,
  "scheduled": false,
  "jobId": "abc-123-def",
  "message": "Email queued for sending",
  "statusUrl": "/v1/send/abc-123-def"
}

GET/v1/send/:jobId

Check the delivery status of a sent email.

Authorizations

Authorizationstring · headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your API Key.

Path Parameters

jobIdstringrequired

Job ID returned from the send endpoint

GET /v1/send/:jobId

curl https://api.posthawk.dev/v1/send/{jobId} \
  -H "Authorization: Bearer your_api_key"

Response

{
  "userId": "user-uuid",
  "status": "completed",
  "result": { "messageId": "ses-message-id" }
}

Errors

Templates