Categories
Every email you send through Bird belongs to a category — a classification of why you are sending, set with the category field on POST /v1/email/messages. The category does not change how the message is built or delivered; it changes which suppression records are allowed to block it. A recipient who unsubscribed from your newsletter has told you something about marketing mail, not about password resets — categories are how Bird tells those two intents apart.
There are two built-in categories in v1, and they are aliases rather than resources you create: you reference them by name on each send, and there is no category-management API.
The two categories
- marketing — mail the recipient chose to receive and can choose to stop receiving: marketing campaigns, newsletters, product announcements, promotional offers. Anything where "I don't want this anymore" is a valid and respected answer.
- transactional — mail the recipient's own action requires: password resets, email verification, one-time codes, order receipts, security and account alerts. The recipient needs these to use your product, regardless of their marketing preferences.
The test is not how the message looks but what happens if it doesn't arrive. If a missing message breaks a flow the recipient initiated, it is transactional; if it is something you initiated to reach them, it is marketing.
How the category drives suppression policy
Each suppression record carries an applies_to policy, and the category decides whether that policy matches the send. From the category's point of view, the suppression matrix reads like this:
| Suppression reason | marketing category | transactional category |
|---|---|---|
| hard_bounce | Blocked | Blocked |
| complaint | Blocked | Allowed |
| unsubscribe | Blocked | Allowed |
| manual | Blocked | Blocked |
The asymmetry is deliberate. hard_bounce means the address does not exist — sending is pointless in any category — and manual is a deliberate decision by your team that Bird never second-guesses, so both block everything. complaint and unsubscribe are preference signals about unwanted mail: they block the marketing category, but a recipient who reported your newsletter as spam still needs their password reset to arrive, so transactional sends deliver through them.
Suppressed recipients in either category are rejected visibly, never silently dropped — each one appears in the message's recipient list with an inspectable reason. See suppressions for the full behavior.
The default — and why marketing sends must opt in
When you omit category, it defaults to transactional, independent of which endpoint you call.
That default makes the common mistake an easy one: marketing content sent without an explicit category rides the transactional policy, which means complaints and unsubscribes do not stop it. Mailing people who have unsubscribed or reported spam is both a deliverability risk and, in many jurisdictions, a compliance problem. Always set category: "marketing" explicitly on marketing, newsletter, and announcement sends so those preference signals are honored:
Codevoorbeeld
{
"from": "news@yourdomain.com",
"to": ["subscriber@example.com"],
"subject": "June product update",
"html": "<p>What's new this month...</p>",
"category": "marketing"
}Relying on the default is fine for the mail the default is named after — receipts, resets, verification — and wrong for everything else.
Categories as an analytics dimension
The category is preserved on the message and echoed back wherever the message appears: the send response includes category, reads of the message return it, and event payloads carry it through to your webhooks. That makes it a clean dimension for slicing — separating marketing and operational mail in your delivery, bounce, and engagement numbers without tagging every send yourself.
No category management in v1
marketing and transactional are the complete set: there is no API to create, rename, or configure categories, and no per-category settings to manage. The field is a classification on each send, validated against those two values. If you need finer-grained segmentation today, use tags alongside the category.
Related pages
- Sending email — the full POST /v1/email/messages payload, including category
- Suppressions — the suppression list, the four reasons, and how addresses get added
- API reference — full request and response schemas