obanox API

Connect your shop, CMS or app to obanox: send transactional emails through your newsletter's verified domain, publish newsletter posts and keep your subscriber list in sync.

Base URL

All endpoints live under:

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:

Create them in your obanox account under Account → API. Every key works for all newsletters of your account and for all APIs. You can create several named keys, e.g. one per integration, and delete one without affecting the others.

Your newsletter's slug

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://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 the id of what was created: 202 Accepted for a transactional email, which is sent right after in the background, and 201 Created for a post or a new subscriber. Other successful requests return 200 OK. Subscriber API responses also carry success and message, for compatibility with its earlier version.

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." }

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:

• Posts API: every successful request creates a new post, and a retry may create and send it twice. Check under Posts in your account, or with GET on the post, before retrying.
• Subscriber API: safe to retry; adding an existing address or removing a missing one is no error.
• 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

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.