Email History

Retrieve information about emails you’ve sent through Lettr. Query your email history to check delivery status, view recipient details, and audit your sending activity.

List Sent Emails

Retrieve a paginated list of emails sent from your account:

curl -X GET "https://app.lettr.com/api/emails" \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

Query Parameters

Parameter	Type	Required	Description
`per_page`	integer	No	Number of results per page (1-100, default: 25)
`cursor`	string	No	The `next_cursor` value from the previous response
`recipients`	string	No	Filter by recipient email address
`from`	string	No	Only emails sent at or after this time (ISO 8601). Defaults to the start of the retained window, about 10 days ago
`to`	string	No	Only emails sent before this time (ISO 8601), exclusive — an email sent at exactly this time is not returned. Defaults to now and must be after `from`

Response

{
  "message": "Emails retrieved successfully.",
  "data": {
    "events": {
      "data": [
        {
          "event_id": "abc123def456",
          "type": "injection",
          "timestamp": "2024-01-15T10:30:00Z",
          "request_id": "7582751837467401763",
          "message_id": "0000abcd1234efgh",
          "subject": "Welcome to Acme",
          "friendly_from": "Acme Team <hello@acme.com>",
          "sending_domain": "acme.com",
          "rcpt_to": "customer@example.com",
          "recipient_domain": "example.com",
          "mailbox_provider": "gmail",
          "click_tracking": true,
          "open_tracking": true,
          "transactional": true,
          "msg_size": 15234,
          "injection_time": "2024-01-15T10:30:00Z"
        }
      ],
      "total_count": 150,
      "from": "2024-01-05T00:00:00+00:00",
      "to": "2024-01-15T10:35:00+00:00",
      "pagination": {
        "next_cursor": "eyJjdXJzb3IiOi...",
        "per_page": 25
      }
    }
  }
}

The emails are in data.events.data. data.events.from and data.events.to show the time window that was actually searched, which can differ from the one you asked for (see Search Window).

List Email Events

GET /emails returns one entry per sent email (its injection event). To see everything that happened afterwards — deliveries, bounces, delays, opens, clicks — use GET /emails/events:

curl -X GET "https://app.lettr.com/api/emails/events?events=delivery,bounce&recipients=customer@example.com" \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

It accepts the same from, to, per_page, and cursor parameters, plus events, transmissions, and bounce_classes filters, and returns the same data.events shape. See List Email Events for every parameter and field.

Search Window

Lettr keeps sent emails and their events for about 10 days, so both GET /emails and GET /emails/events can only search that window:

If you leave out from, the search starts at the beginning of the retained window.
If from is earlier than that, it is moved forward to the start of the retained window instead of failing. The from in the response tells you where the search actually started.
If the whole range ends before the retained window starts, the response is empty.
If to is not after from, the request fails with a 422 validation error.

Get Email by Request ID

Retrieve details for a specific email using its request ID:

curl -X GET "https://app.lettr.com/api/emails/7582751837467401763" \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

The request ID is returned when you send an email:

const result = await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Hello',
  html: '<p>Message content</p>'
});

// Store the request_id for later lookup
const requestId = result.data.request_id;

Response

{
  "message": "Email retrieved successfully.",
  "data": {
    "transmission_id": "7582751837467401763",
    "state": "delivered",
    "scheduled_at": null,
    "from": "hello@acme.com",
    "from_name": null,
    "subject": "Welcome to Acme",
    "recipients": ["customer@example.com"],
    "num_recipients": 1,
    "events": [
      {
        "event_id": "event-delivery-1",
        "type": "delivery",
        "timestamp": "2024-01-15T10:31:00.000Z",
        "request_id": "7582751837467401763",
        "rcpt_to": "customer@example.com",
        "subject": "Welcome to Acme"
      },
      {
        "event_id": "event-injection-1",
        "type": "injection",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "request_id": "7582751837467401763",
        "rcpt_to": "customer@example.com",
        "subject": "Welcome to Acme"
      }
    ]
  }
}

state is derived from the events: scheduled, delivered, bounced, or failed. If no email with that request ID is found in the retained window, the endpoint returns 404. See Get Email Detail for every field.

Response Fields

Each entry in data.events.data from GET /emails contains:

Field	Type	Description
`event_id`	string	Unique identifier for this event
`timestamp`	string	When the event occurred (ISO 8601)
`request_id`	string	The transmission/request ID from sending
`message_id`	string	Unique message identifier
`subject`	string	Email subject line
`friendly_from`	string	Formatted sender address with name
`sending_domain`	string	Domain the email was sent from
`rcpt_to`	string	Recipient email address
`recipient_domain`	string	Recipient’s email domain
`mailbox_provider`	string	Recipient’s email provider (gmail, outlook, etc.)
`mailbox_provider_region`	string	Geographic region of the provider
`sending_ip`	string	IP address used for sending
`click_tracking`	boolean	Whether click tracking was enabled
`open_tracking`	boolean	Whether open tracking was enabled
`transactional`	boolean	Whether this was marked as transactional
`msg_size`	integer	Email size in bytes
`injection_time`	string	When the email was queued for delivery
`rcpt_meta`	object	Custom metadata attached to the email

Filtering by Date Range

Query emails within a specific time period:

// Get emails from the last 7 days
const sevenDaysAgo = new Date();
sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);

const response = await fetch(
  `https://app.lettr.com/api/emails?from=${sevenDaysAgo.toISOString()}&to=${new Date().toISOString()}`,
  {
    headers: {
      'Authorization': 'Bearer lttr_xxxxxxxxxxxx'
    }
  }
);

const emails = await response.json();

Filtering by Recipient

Find all emails sent to a specific address:

curl -X GET "https://app.lettr.com/api/emails?recipients=customer@example.com" \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

Pagination

Use cursor-based pagination to retrieve large result sets:

async function getAllEmails() {
  let allEmails = [];
  let cursor = null;

  do {
    const url = cursor
      ? `https://app.lettr.com/api/emails?cursor=${encodeURIComponent(cursor)}`
      : 'https://app.lettr.com/api/emails?per_page=100';

    const response = await fetch(url, {
      headers: {
        'Authorization': 'Bearer lttr_xxxxxxxxxxxx'
      }
    });

    const { data } = await response.json();
    allEmails = allEmails.concat(data.events.data);
    cursor = data.events.pagination.next_cursor;

  } while (cursor);

  return allEmails;
}

Pass next_cursor back as the cursor parameter exactly as you received it — don’t decode, modify, or build it yourself. The cursor already carries the filters and time window of the first page, so later pages stay consistent. A cursor that didn’t come from a previous response fails with a 422 validation error. Cursors issued before the current format still work. The same pagination works for GET /emails/events.

Email history is kept for about 10 days. For longer retention, use webhooks to store email events in your own database.

Use Cases

Audit Trail

Track all emails sent to a specific customer:

async function getCustomerEmailHistory(email) {
  const response = await fetch(
    `https://app.lettr.com/api/emails?recipients=${encodeURIComponent(email)}`,
    {
      headers: {
        'Authorization': 'Bearer lttr_xxxxxxxxxxxx'
      }
    }
  );

  const { data } = await response.json();
  return data.events.data;
}

Verify Delivery

Check what happened to a specific email:

async function checkEmailStatus(requestId) {
  const response = await fetch(
    `https://app.lettr.com/api/emails/${requestId}`,
    {
      headers: {
        'Authorization': 'Bearer lttr_xxxxxxxxxxxx'
      }
    }
  );

  if (response.status === 404) {
    return { found: false };
  }

  const { data } = await response.json();

  return {
    found: true,
    state: data.state,
    events: data.events
  };
}

Daily Send Report

Generate a report of emails sent today:

async function getDailySendReport() {
  const today = new Date();
  today.setHours(0, 0, 0, 0);

  const response = await fetch(
    `https://app.lettr.com/api/emails?from=${today.toISOString()}&per_page=100`,
    {
      headers: {
        'Authorization': 'Bearer lttr_xxxxxxxxxxxx'
      }
    }
  );

  const { data } = await response.json();

  return {
    totalSent: data.events.total_count,
    emails: data.events.data.map(e => ({
      to: e.rcpt_to,
      subject: e.subject,
      sentAt: e.timestamp
    }))
  };
}

Error Responses

Status	Error	Description
401	Unauthorized	Invalid or missing API key
404	Not Found	Email with specified request ID not found
422	Validation Error	Invalid query parameters, `to` not after `from`, or a `cursor` that didn’t come from a previous response
500	Server Error	Internal error, retry the request
503	`auth_unavailable`	Lettr couldn’t verify your API key right now. Retry after the `Retry-After` delay

Analytics

Aggregate email performance metrics

Webhooks

Real-time email event notifications

Metadata

Attach custom data to emails

Idempotency

Prevent duplicate sends

Documentation

Quickstart

Learn

Integrations

Resources

Email History

List Sent Emails

Query Parameters

Response

List Email Events

Search Window

Get Email by Request ID

Response

Response Fields

Filtering by Date Range

Filtering by Recipient

Use Cases

Audit Trail

Verify Delivery

Daily Send Report

Error Responses

Analytics

Webhooks

Metadata

Idempotency

​List Sent Emails

​Query Parameters

​Response

​List Email Events

​Search Window

​Get Email by Request ID

​Response

​Response Fields

​Filtering by Date Range

​Filtering by Recipient

​Pagination

​Use Cases

​Audit Trail

​Verify Delivery

​Daily Send Report

​Error Responses

​Related Topics

Analytics

Webhooks

Metadata

Idempotency

List Sent Emails

Query Parameters

Response

List Email Events

Search Window

Get Email by Request ID

Response

Response Fields

Filtering by Date Range

Filtering by Recipient

Pagination

Use Cases

Audit Trail

Verify Delivery

Daily Send Report

Error Responses

Related Topics