# 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`](/docs/api/reference/create-email-message). The category does not change how the message is built or delivered; it changes which [suppression](/docs/guides/email/suppressions) 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](/docs/guides/email/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](/docs/guides/email/unsubscribe-links), and stays compliant with no extra work. (Mail submitted [over SMTP](/docs/guides/email/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:

```json
{
  "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](/docs/api/reference/list-email-messages) filters by category, the [stats API](/docs/api/reference/get-email-stats-by-category) breaks metrics down by it, and the dashboard [email log](/docs/guides/email/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](/docs/guides/email/sending-email#tags-vs-metadata) alongside the category.

## Next steps

- [Sending email](/docs/guides/email/sending-email): the full `POST /v1/email/messages` payload, including `category`
- [Suppressions](/docs/guides/email/suppressions): the suppression list, the reasons, and the full category matrix
- [API reference](/docs/api/reference/create-email-message): full request and response schemas