Sending
Single sends, batches, scheduling, idempotency and tags.
POST /emails accepts from, to and subject, plus at least one of html or text. The to array holds between 1 and 50 recipients. A full or sending key can call it, in live or test mode.
POST /emails/batch accepts an emails array of 1–100 send requests. Every item is validated before any item is stored. If one item is invalid, none is stored. The usage debit and the stored rows commit together. The data array is in request order. After that commit, each queued email is enqueued on its own. An enqueue error does not remove the accepted row.
List emails
GET /emails needs a full key. A sending or read_only key receives 403. The page is newest first. Results stay inside the retention window. The default window is 30 days.
| Query | Meaning |
|---|---|
limit | Page size from 1 to 100. The default is 50. |
after | next_cursor from the previous page. The value is an email ID (em_…). Any other value returns 400. |
status | One of queued, scheduled, sent, delayed, delivered, bounced, complained, failed, canceled. |
domain_id | Only mail for that domain. |
test_mode | true or false. Omit it to include both modes. The key mode does not hide the other mode. |
The response has data. A full page also has next_cursor. Each item has id, status, created_at, from, to, subject, test_mode and domain_id. status_detail is present when the provider sent a detail. There is no cancel operation.
curl 'https://api.sendtier.com/emails?limit=50&status=queued&test_mode=false' \
-H "Authorization: Bearer $SENDTIER_API_KEY"Scheduling
Set scheduled_at to an ISO 8601 UTC time from now through 72 hours ahead. The initial status is scheduled; cron moves due emails into the send queue. Otherwise, the initial status is queued. Both return 202 upon acceptance. The current API has no email cancellation operation.
Idempotency
Supply an Idempotency-Key of 1–255 bytes when retrying. OpenAPI declares the header on POST /emails, POST /emails/batch, POST /domains, POST /webhooks, POST /suppressions and POST /webhook-deliveries/{delivery_id}/resend. The server also stores a key sent to POST /domains/{domain_id}/verify, which does not declare the header. POST /api-keys and POST /organizations ignore the header. Those two create another resource when retried. Keys are scoped to the tenant and retained for 24 hours before cron cleanup. The key is tied to the HTTP method, path, exact request body bytes and API key mode (test or live). A changed request, or an identical request still in progress, returns 409 idempotency_conflict. A completed replay returns the stored status and body with Idempotent-Replayed: true. Server errors release the claim so a retry can run. A 429 is not stored, so the same key can be retried after Retry-After.
Tags
tags is an object whose values are strings, for example {"category":"receipt"}. Tags are stored on the email and returned by the email-detail endpoint. They are not a string array. The current webhook envelope merges event data; it does not automatically include email tags.
Sources: send handlers (internal/api/emails.go), validation and scheduling horizon (internal/domain/email.go), idempotency (internal/api/idempotency.go), cleanup and scheduled sends (internal/cron/cron.go), webhook payload (internal/webhook/payload.go), OpenAPI (openapi/openapi.yaml).