Core concepts

A quick orientation to the key objects and ideas in the Developer Email API before you start building.

---

Messages

Every send creates a message with a unique ID. You get the ID back in the API response and can use it to check status or retrieve the message.

Message status lifecycle

Status	Meaning
queued	Accepted by the API. Delivery is in progress.
sent	Handed off to the delivery infrastructure.
delivered	The receiving mail server confirmed receipt.
bounced	The address rejected delivery (hard bounce or complaint).
failed	Delivery could not be completed.

queued is the status you receive immediately in a successful POST /v1/emails/send response. Status updates to sent, then delivered or bounced asynchronously as delivery events arrive. Use GET /v1/emails/:message_id to poll for the latest status.

---

Content sources

Every send requires exactly one content source:

Field	What it is	Best for
html	A raw HTML string	Full control over markup
template_id	ID of a template saved in the dashboard	Reusing designed templates across sends
starter_template	Slug of a built-in starter template	Quick sends without writing HTML

You cannot mix sources in a single request. For the full list of available starter_template slugs, call GET /v1/starter-templates.

---

Sending domains

All outbound email must come from a verified sending domain — a domain you own and have configured with the required DNS records (SPF and DKIM).

Verification proves to receiving mail servers that Brixus365 is authorised to send on your domain’s behalf. Without it, your email is likely to land in spam or be rejected outright.

You verify a domain once in Settings → Email Setup. After that, any sender address on that domain can be used immediately. See Verify your sending domain for the step-by-step.

---

API keys and scopes

API keys authenticate your requests and control what your application can do.

Key prefixes

Prefix	Account type
bx_live_*	Full account (free or paid)
bx_test_*	Preview account (sandbox, lower send limits)

Scopes

Each key carries one or more scopes that limit what it can access. A key with only emails:send cannot list messages; a key with emails:read cannot send. Create keys with the minimum scopes needed for each integration.

Manage keys in Settings → API Keys.

---

Idempotency

If a send request times out or you’re unsure whether it was received, you can safely retry without risk of duplicate sends by using an idempotency key.

Add an Idempotency-Key header with a unique string — a UUID works well:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

If the same key is sent again within 24 hours, the API returns the original response instead of processing a new send. Reusing a key with a different request body returns a 409 idempotency_key_mismatch error.

---

Single send vs batch send

	Single (POST /v1/emails/send)	Batch (POST /v1/emails/batch)
Messages per request	1	Up to 100
Recipients per message	Up to 50 (to + cc + bcc)	Up to 50 per message, 1,000 total
Use when	One message to one recipient set	Sending many personalised messages at once

Batch sends return one message ID per message. Each message is tracked independently.

---

What’s next

You want to…	Go to
Make your first send	Quickstart
See what’s included on each plan	Limits
Explore the full API	API Reference
Understand error responses	Errors