obanox API

Connect your shop, CMS or app to obanox: send transactional emails through your newsletter's verified domain.

Transactional email API

Send password resets, order confirmations and other personal emails from your own domain.

Base URL

All endpoints live under:

https://www.obanox.com/api/v1

Requests must use HTTPS. Every request belongs to one of your newsletters, which is part of the path: /api/v1/{slug}/….

Authentication

Authenticate every request with your API key and API secret, sent as headers:

Header	Value
`API-KEY`	Your API key
`API-SECRET`	Your API secret

Create them in your obanox account under Settings → API access. One pair of credentials works for all newsletters of your account and for all APIs.

Keep your API secret on your server. Never put it into a website, a mobile app or a public repository. Anyone with the secret can post and send in your name. If it leaks, create new credentials and delete the old ones.

The slug is the short name in your newsletter's address: my-newsletter in https://my-newsletter.obanox.com. A request for a newsletter of another account returns 403.

Requests and responses

Send a JSON object with Content-Type: application/json. Responses are JSON, too. A typical request:

curl -X POST "https://www.obanox.com/api/v1/my-newsletter/send" \
  -H "Content-Type: application/json" \
  -H "API-KEY: your-api-key" \
  -H "API-SECRET: your-api-secret" \
  -d '{"from": "[email protected]", "to": "[email protected]", "subject": "Hello", "text": "Hello from the obanox API"}'

Successful requests return 202 Accepted with the id of what was created: the work (sending) happens right after, in the background.

Errors

Errors return a 4xx or 5xx status and a JSON body with an error message:

{ "error": "The from address is not on a verified sender domain." }

Status	Meaning
`401`	The `API-KEY` / `API-SECRET` headers are missing or wrong.
`403`	The newsletter doesn't exist or belongs to another account.
`413`	The request body is too large.
`422`	The request is invalid; see `error`. Repeating it unchanged won't help.
`429`	A limit of your plan is reached, e.g. the daily email limit.
`5xx`	A temporary problem on our side. Retry after a short wait.

Retries

If a request times out or returns 5xx, you can't tell whether it was processed. Retry with a growing wait (for example after 1 minute, then 5 minutes), and avoid duplicates:

Transactional email API: there is no idempotency key yet; a retry may send the email twice. For critical emails, log the request before retrying.

Don't retry 4xx errors unchanged; only 429 succeeds later, once the limit resets.

Limits

API	Request size	Other limits
Transactional email	512 KB	One recipient per request; daily emails according to your plan.

Versioning

The version is part of the path (/api/v1). Within a version we only make additive changes: new optional fields, new response fields, new error messages. Ignore response fields you don't know, and rely on the status code rather than on the exact error text. Breaking changes get a new version.