Metadata

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.

Feature	Metadata	Tag
Structure	Key-value pairs	Single string (max 64 chars)
Values	Strings only	Plain string
Where it appears	Webhooks, dashboard	Analytics dashboard filters and breakdowns
Best for	Detailed 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

Limit	Value
Max keys	50
Max key length	40 characters
Max value length	500 characters
Max total size	8 KB

Don’t store sensitive information (passwords, API keys, PII) in metadata. Metadata is visible in the dashboard and webhook payloads.

Documentation

Quickstart

Learn

Integrations

Resources

Adding Metadata

Metadata in Webhooks

Use Cases

Order Tracking

User Attribution

Analytics

Debugging

Metadata vs Tags

Example: Full Tracking Setup

Limits

​Adding Metadata

​Metadata in Webhooks

​Use Cases

Order Tracking

User Attribution

Analytics

Debugging

​Metadata vs Tags

​Example: Full Tracking Setup

​Limits

Adding Metadata

Metadata in Webhooks

Use Cases

Metadata vs Tags

Example: Full Tracking Setup

Limits