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	Pagination cursor for next page
`recipients`	string	No	Filter by recipient email address
`from`	string	No	Filter emails sent after this date (ISO 8601)
`to`	string	No	Filter emails sent before this date (ISO 8601)

Response

{
  "message": "Emails retrieved successfully.",
  "data": {
    "results": [
      {
        "event_id": "abc123def456",
        "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,
    "pagination": {
      "next_cursor": "eyJsYXN0X2V2...",
      "per_page": 25
    }
  }
}

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": {
    "results": [
      {
        "event_id": "abc123def456",
        "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",
        "raw_rcpt_to": "customer@example.com",
        "recipient_domain": "example.com",
        "mailbox_provider": "gmail",
        "mailbox_provider_region": "us",
        "sending_ip": "192.0.2.1",
        "click_tracking": true,
        "open_tracking": true,
        "transactional": true,
        "msg_size": 15234,
        "injection_time": "2024-01-15T10:30:00Z",
        "rcpt_meta": {
          "order_id": "ORD-12345",
          "user_id": "usr_abc123"
        }
      }
    ],
    "total_count": 1,
    "pagination": {
      "next_cursor": null,
      "per_page": 25
    }
  }
}

Response Fields

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=${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.data.results);
    cursor = data.data.pagination.next_cursor;

  } while (cursor);

  return allEmails;
}

Email history is retained for 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.results;
}

Verify Delivery

Check if a specific email was successfully queued:

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

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

  if (data.total_count === 0) {
    return { found: false };
  }

  return {
    found: true,
    email: data.results[0],
    injectedAt: data.results[0].injection_time
  };
}

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.total_count,
    emails: data.results.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
500	Server Error	Internal error, retry the request

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

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

​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

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