Skip to main content
Tags let you label emails with a single string identifier so you can group and analyze them in the Analytics dashboard. Every email can carry one tag (max 64 characters), and you can filter and break down metrics — sent, delivered, bounced, opened, clicked — by that tag.

​
Adding a Tag via API

Include the tag field in your send request: 
POST /api/emails
Authorization: Bearer lttr_xxxxxxxxxxxx

{
  "from": "marketing@yourdomain.com",
  "to": ["subscriber@example.com"],
  "subject": "Weekly Newsletter",
  "html": "<p>This week's update...</p>",
  "tag": "welcome"
}

​
Adding a Tag via PHP SDK

Use the ->tag() method on the email builder: 
$response = $lettr->emails()->send(
    $lettr->emails()->create()
        ->from('marketing@yourdomain.com')
        ->to(['subscriber@example.com'])
        ->subject('Weekly Newsletter')
        ->html('<p>This week\'s update...</p>')
        ->tag('welcome')
);

​
Automatic Tags from Templates

When you send an email using a template_slug, Lettr automatically sets the tag to the template slug on the server. You don’t need to pass a tag yourself — your analytics are grouped by template out of the box. This also means that each template in the Emails dashboard shows Sent, Opened, and Rate columns, giving you per-template engagement stats without any extra configuration.
You can override the automatic tag by passing an explicit tag in the request. The explicit tag takes priority.

​
Tags in the Dashboard

Tags appear in two places in the Lettr dashboard:

​
Analytics by Tag

The home dashboard includes an Analytics by Tag widget that shows sending stats for the last 30 days grouped by tag — Sent, Opened, and Rate at a glance.

​
Analytics Filtering and Breakdowns

On the Analytics page you can use tags in two ways:
  • Filter by Tag — Show only data for emails with a specific tag. Open the Configure modal, go to the Filters tab, and select “Tag” as the filter type.
  • Break down by Tag — Use the “Break Down By” dropdown below the chart to see your metrics split by tag. This lets you compare performance across different email categories at a glance.

Filtering and Breakdowns

Learn more about the Configure modal, filters, and breakdowns

​
Tag Rules

RuleDetail
Maximum length64 characters
Tags per emailOne
FormatPlain string — letters, numbers, hyphens, underscores

​
Tags vs Metadata

Tags and metadata serve different purposes:
TagsMetadata
PurposeAnalytics groupingPer-email tracking data
StructureSingle stringKey-value pairs
Where it appearsAnalytics dashboard filters and breakdownsWebhooks, API queries, dashboard
Best forComparing performance across email categoriesLinking emails to orders, customers, or internal IDs
Use a tag when you want to group emails in the Analytics dashboard (e.g., welcome-series, order-confirmation). Use metadata when you need to attach structured data for webhooks or API queries (e.g., orderId, customerId).

Metadata

Learn how to attach key-value data to emails for detailed tracking