API reference

The NextMail REST API is JSON-only, scoped per tenant via your API key, and versioned. Every request requires Authorization: Bearer nm_… in the header.

Endpoints

POST/v1/emailsSend a transactional email

GET/v1/emails/:idRetrieve an email by message id

GET/v1/emailsList emails with filters

POST/v1/templatesCreate a template

GET/v1/templates/:slugFetch a template by slug

GET/v1/suppressionsList the suppression list

POST/v1/suppressionsManually suppress an address

DELETE/v1/suppressions/:emailRemove an address from suppression

POST/v1/webhooksRegister a consumer webhook

GET/v1/webhooksList registered webhooks

POST/v1/api-keysIssue an API key (admin scope)

GET/v1/api-keysList API keys (prefix + metadata, not the raw key)

POST /v1/emails

The primary send endpoint. Accepts a JSON body and returns a queued message id.

Request

application/json

{
  "from":     "noreply@mail.example.com",
  "to":       "user@example.com",
  "replyTo":  "support@example.com",
  "subject":  "Your password reset",
  "html":     "<p>Click to reset.</p>",
  "text":     "Click to reset.",
  "template": "password-reset",
  "data":     { "name": "Sarah", "resetUrl": "https://..." },
  "tags":     ["flow:password-reset"],
  "metadata": { "userId": "u_42" }
}

Either html + text or template + data must be present. Templates win when both are sent.

Response

HTTP 202 Accepted

{
  "messageId": "msg_8gK9p2x1WqYz",
  "status":    "QUEUED",
  "queuedAt":  "2026-05-27T12:48:21.991Z"
}

Errors

400 — invalid body (missing field, malformed email)
401 — invalid or revoked API key
403 — API key lacks the emails:send scope
409 — recipient is on the suppression list
429 — rate limit exceeded; respect Retry-After

Full per-endpoint details ship with the OpenAPI spec under /v1/openapi.json.