Documentation
Sign inGet started
Jetzt starten
Anleitungen
API-Referenz
SDKs
CLI
Wissensdatenbank
Changelog

Categories

Every email you send has a category saying why you are sending it, set with the category field on POST /v1/email/messages. It takes one of two values, marketing or transactional, and it has one effect: it decides which suppression records are allowed to block the message.
A recipient who unsubscribed from your newsletter has told you something about marketing mail. They have said nothing about password resets. The category is how we tell those two intents apart.

The two categories

  • marketing: mail the recipient chose to receive and can choose to stop receiving. Campaigns, newsletters, product announcements, promotional offers. Anything where "I don't want this anymore" is an answer you have to respect.
  • transactional: mail the recipient's own action requires. Password resets, email verification, one-time codes, order receipts, security and account alerts. These have to arrive whatever the recipient's marketing preferences are.
Ask what happens if the message never arrives. If a flow the recipient started breaks, it is transactional. If you started the conversation, it is marketing.
These two are the complete set: no API creates or configures a category, and the field is validated against those values. For segmentation finer than this, use tags alongside the category.

How the category drives suppression policy

The contract is one line: marketing is blocked by every suppression reason, and transactional delivers through complaint and unsubscribe suppressions. Hard bounces and manual suppressions block both.
The asymmetry follows from what each reason means. A hard bounce means the address does not exist, so sending is pointless whatever the category. A manual suppression is your own team's decision, which we never second-guess. Complaints and unsubscribes are preferences about unwanted mail: they stop your marketing sends, while a recipient who reported your newsletter as spam still gets their password reset.
Blocked recipients are rejected where you can see them, one line per recipient with the reason attached. Suppressions has the reason-by-reason table and covers how addresses reach the list.

The default, and why transactional sends must opt out

Omit category and the send is marketing. That fails in the safe direction: mail sent without an explicit category honors unsubscribes and complaints and has an unsubscribe link, so a campaign is compliant with no extra work.
Two send paths take their category from elsewhere. A send that uses a stored template and omits category takes the template's own classification, so a template created as transactional sends as transactional. Set category on the send to classify one message differently, and the send's value wins. Mail submitted over SMTP takes its category from the API key's SMTP configuration, which is transactional for a key you have not configured.
The flip side of the default is that operational mail has to opt out. Send a password reset with no category and we treat it as marketing. It has an unsubscribe link it should not have, and anyone who unsubscribed from your newsletter stops receiving it even though their own click triggered it. Set category: "transactional" on receipts, resets, verification codes, and account alerts:
Codebeispiel
{
  "from": "no-reply@yourdomain.com",
  "to": ["delivered@messagebird.dev"],
  "subject": "Reset your password",
  "html": "<p>Click the link below to reset your password...</p>",
  "category": "transactional"
}

Categories as an analytics dimension

The category stays on the message and comes back wherever the message appears, so it slices your delivery, bounce, and engagement numbers into marketing and operational traffic without you tagging every send. The message list filters by category, the stats API breaks metrics down by it, and the dashboard email log offers the same filter.

Next steps