Skip to main content
Metadata lets you attach arbitrary key-value pairs to any email you send through Lettr. These pairs travel with the email through the entire delivery lifecycle — appearing in webhook payloads and the dashboard — so you can correlate emails with your application’s data model. Common uses include linking emails to orders, customers, support tickets, or internal request IDs for debugging.

​
Adding Metadata

Include a metadata object in your send request. All values must be strings: 
await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Order Confirmation',
  html: '<p>Your order is confirmed!</p>',
  metadata: {
    orderId: 'order_12345',
    customerId: 'cust_67890',
    orderTotal: '99.99',
    source: 'checkout'
  }
});

​
Metadata in Webhooks

When Lettr delivers a webhook event for an email that carries metadata, the full metadata object is included in the payload. This means your webhook handler can read the same keys you attached at send time and use them to look up the relevant order, customer, or transaction in your database without making additional API calls. 
{
  "type": "message.delivery",
  "data": {
    "request_id": "7582751837467401763",
    "to": "recipient@example.com",
    "metadata": {
      "orderId": "order_12345",
      "customerId": "cust_67890",
      "orderTotal": "99.99",
      "source": "checkout"
    }
  }
}

​
Use Cases

Order Tracking

Link emails to orders for support and auditing.

User Attribution

Track which user triggered each email.

Analytics

Segment email performance by custom dimensions.

Debugging

Include request IDs for easier troubleshooting.

​
Metadata vs Tags

Lettr supports both metadata and tags on emails. They serve different purposes: metadata stores structured key-value data for detailed tracking, while a tag is a single string label for analytics grouping.
FeatureMetadataTag
StructureKey-value pairsSingle string (max 64 chars)
ValuesStrings onlyPlain string
Where it appearsWebhooks, dashboardAnalytics dashboard filters and breakdowns
Best forDetailed tracking data (order IDs, customer IDs)Grouping emails for analytics (e.g., welcome-series)

​
Example: Full Tracking Setup

await lettr.emails.send({
  from: 'orders@example.com',
  to: ['customer@example.com'],
  subject: 'Order #12345 Confirmed',
  html: orderConfirmationHtml,

  // Tag for analytics grouping
  tag: 'order-confirmation',

  // Metadata for detailed tracking
  metadata: {
    orderId: 'order_12345',
    customerId: 'cust_67890',
    orderTotal: '299.99',
    currency: 'USD',
    itemCount: '3',
    shippingMethod: 'express',
    requestId: 'req_xyz789'
  }
});

​
Limits

LimitValue
Max keys50
Max key length40 characters
Max value length500 characters
Max total size8 KB
Don’t store sensitive information (passwords, API keys, PII) in metadata. Metadata is visible in the dashboard and webhook payloads.