API

REST API reference

All endpoints, parameters, example requests and responses. Authentication: API key (Bearer).

Quick example

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome",
    "html": "<h1>Hello!</h1>"
  }'

The API key is obtained from the panel → Developer tab. Separate, scoped keys are recommended for production and test environments.

Authentication

Every request carries an Authorization: Bearer YOUR_API_KEY header. Keys are created in the panel, shown once at creation, then hashed. If you lose a key, you generate a new one and revoke the old — the old key is disabled the moment it is revoked.

  • Scope-based permissions: 30 scopes (send · campaign · template · webhook · domain · ...). A key only uses the areas you allow.
  • IP allowlist: you can restrict production keys to specific IP/CIDR ranges.
  • Time limit: you can assign a TTL to keys; they expire automatically when the time is up.
  • Audit log: every key use is logged with timestamp + endpoint + result.

Idempotency-Key

Use the Idempotency-Key header on POST requests — a second request with the same key returns the first response again, with no duplicate send. UUIDv4 recommended; the key is stored for 24 hours. 

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer sn_live_•••" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-..." \
  ...

Error format

All error responses share the same envelope — code + message + request-specific detail:

{
  "error": {
    "code":    "invalid_recipient",
    "message": "Recipient address does not match the format rule",
    "field":   "to",
    "request_id": "req_01HX8K..."
  }
}

HTTP status codes follow RFC 7231. Temporary errors are 5xx + retry-after; permanent 4xx errors are not subject to retry.

Rate limit

The limit depends on your plan and is displayed in real time in the panel. Every response includes the headers:

  • X-RateLimit-Limit · requests allowed in the window
  • X-RateLimit-Remaining · remaining request allowance
  • X-RateLimit-Reset · when the window resets (Unix epoch)

If you receive a 429, wait for the duration in the Retry-After header. The SDKs do this automatically.

Versioning

The version is required in the URL (/v1/). Moving to a new version comes with a 12-month deprecation window + changelog notice. Breaking changes never ship silently — as soon as a deprecated endpoint is used, a warning header is returned.

Endpoint list

  • POST /v1/messages Send a single or bulk email.
  • GET /v1/messages/{id} Query the status of a specific message.
  • GET /v1/messages Message list, with filtering and pagination.
  • POST /v1/templates Create a new template (Handlebars + Liquid mix).
  • GET /v1/templates/{id} Template detail.
  • POST /v1/suppressions Add an address to the suppression list.
  • GET /v1/suppressions Suppression list.
  • POST /v1/webhooks Register a webhook endpoint.
  • GET /v1/events Event stream (sent, delivered, opened, clicked, bounced, complained).
  • GET /v1/domains Your verified domains.

OpenAPI 3.1 spec: /v1/openapi.json — for IDE / Postman import. Every endpoint is documented with its full parameters, example request and response schema.