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.

Bird has two built-in categories, and they are values rather than resources you create: you reference them by name on each send, with 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

The contract is one line: marketing is blocked by every suppression reason; transactional delivers through complaint and unsubscribe suppressions and is still blocked by hard bounces and manual suppressions.

The asymmetry is deliberate. A hard bounce means the address does not exist, so sending is pointless in any category, and a manual suppression is a decision by your team that Bird never second-guesses. Complaints and unsubscribes 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. The full reason-by-reason matrix, and how addresses get onto the list, live in suppressions.

The default, and why transactional sends must opt out

When you omit category on a send or a batch item, it defaults to marketing. That is the safe direction to fail in: content sent without an explicit category honors unsubscribes and complaints, carries the one-click unsubscribe affordances, and stays compliant with no extra work. (Mail submitted over SMTP is the exception: its category comes from the key's SMTP configuration, which defaults to transactional.)

The flip side is that operational mail must opt out. Send a password reset or receipt without an explicit category and Bird treats it as marketing: it gets an unsubscribe header and in-body link it should not carry, and anyone who unsubscribed from your newsletter no longer receives it, even though their own action triggered it. Always set category: "transactional" explicitly on receipts, resets, verification codes, and account alerts:

Exemple de code

{
  "from": "no-reply@yourdomain.com",
  "to": ["customer@example.com"],
  "subject": "Reset your password",
  "html": "<p>Click the link below to reset your password...</p>",
  "category": "transactional"
}

Relying on the default is fine for the mail the default is named after (campaigns, newsletters, announcements) and wrong for everything the recipient's own actions require.

Categories as an analytics dimension

The category is preserved on the message and returned wherever the message appears: the send response includes category, and reads of the message return it. 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. The message list filters by category, the stats API breaks metrics down by it, and the dashboard email log offers the same filter.

No category management

marketing and transactional are the complete set: no API exists 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, use tags alongside the category.

Next steps

Sending email: the full POST /v1/email/messages payload, including category
Suppressions: the suppression list, the reasons, and the full category matrix
API reference: full request and response schemas