Tags
Label emails with your own key-value pairs, then filter by them and read them in webhooks.
Tags are your own labels for an email, as an object of string keys to string values. They are not part of the message the recipient sees.
await flaresend.emails.send({
from: 'Acme <hello@acme.com>',
to: 'ada@example.com',
subject: 'Reset your password',
template: 'password-reset',
data: { resetUrl },
tags: { kind: 'password-reset', user_id: '42' },
});Keys are up to 64 characters and values up to 256. Values must be strings, so send "42", not 42.
Where tags show up
- The email record.
tagson Retrieve an email and List emails. - Filtering. List emails with
tag=key:value, for exampleGET /v1/emails?tag=kind:password-reset. The value is everything after the first colon, and it must match exactly. The dashboard's email filters use the same parameter. - Webhooks. Every webhook payload has the email's tags in
data.tags, so your handler can tell what the email was for without looking it up. - Analytics. Analytics returns the 10 most used
key:valuepairs in the range astopTags.
const { data } = await flaresend.emails.list({ tag: 'user_id:42', status: 'bounced' });Tags Flaresend adds
Flaresend adds some tags itself. They are merged over yours, so avoid these keys:
| Tag | Added to |
|---|---|
broadcast_id | Every email sent by a broadcast. Its value is the broadcast ID. |
resent_from | An email created by the admin resend action. Its value is the ID of the original email. |
Tips
- Tag with IDs you already have (
user_id,order_id,tenant), so you can go from an email to your own records. - Use one key like
kindfor the type of email. It makes thetopTagslist and the email filters useful. - Don't put secrets or personal data in tags. They are stored in plain text and sent to every webhook.