Skip to main content
A tag is a free-form label you attach to a send, a { name, value } pair you choose. Tags are yours to define: a campaign name, an environment, a customer segment, whatever you filter and report on. They belong to the individual message and travel with it through delivery and events. mailkube does not interpret a tag; it stores it and hands it back to you. Tagging a send is optional. A send with no tags is delivered as-is.

Validation rules

Every tag is checked before the send is accepted: A tag that breaks any of these rules (a bad character, an oversized name or value, a missing value key, a duplicate name, or more than 20 tags) makes the whole send fail validation. On REST that is a validation_error; over SMTP it is a 550 5.6.0 reply naming the rule, see Tagging a send.
Tag values are not encrypted and are excluded from aggregate metrics, so never put personal data (a recipient address, a name, anything identifying) in a tag name or value. Use opaque, non-identifying labels.

Where tags surface

Tags follow the message through delivery and reporting:
  • Webhook payloads: every email.* event echoes the tags you attached in its data block, for your receiver to route or record on.
  • Log filtering: a message keeps its tags on its log entry, and your sending logs filter by tag.
  • Dashboard: the Tags Performance view breaks down your sends per tag.

Attaching tags to a send

  • REST: set the tags array on the send request, a list of { "name": ..., "value": ... } pairs.
  • SMTP: add an X-Mailkube-Tags header carrying that same array as JSON.
Both take the identical { name, value } shape and the same validation rules above.