> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

> Attach custom key-value metadata to Lettr emails that travels through delivery and webhooks to link messages to your app's data

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:

```javascript theme={null}
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.

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Order Tracking" icon="box">
    Link emails to orders for support and auditing.
  </Card>

  <Card title="User Attribution" icon="user">
    Track which user triggered each email.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Segment email performance by custom dimensions.
  </Card>

  <Card title="Debugging" icon="bug">
    Include request IDs for easier troubleshooting.
  </Card>
</CardGroup>

## Metadata vs Tags

Lettr supports both metadata and [tags](/learn/sending/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

```javascript theme={null}
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           |

<Warning>
  Don't store sensitive information (passwords, API keys, PII) in metadata. Metadata is visible in the dashboard and webhook payloads.
</Warning>