Skip to main content
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

ParameterTypeRequiredDescription
per_pageintegerNoNumber of results per page (1-100, default: 25)
cursorstringNoPagination cursor for next page
recipientsstringNoFilter by recipient email address
fromstringNoFilter emails sent after this date (ISO 8601)
tostringNoFilter 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

FieldTypeDescription
event_idstringUnique identifier for this event
timestampstringWhen the event occurred (ISO 8601)
request_idstringThe transmission/request ID from sending
message_idstringUnique message identifier
subjectstringEmail subject line
friendly_fromstringFormatted sender address with name
sending_domainstringDomain the email was sent from
rcpt_tostringRecipient email address
recipient_domainstringRecipient’s email domain
mailbox_providerstringRecipient’s email provider (gmail, outlook, etc.)
mailbox_provider_regionstringGeographic region of the provider
sending_ipstringIP address used for sending
click_trackingbooleanWhether click tracking was enabled
open_trackingbooleanWhether open tracking was enabled
transactionalbooleanWhether this was marked as transactional
msg_sizeintegerEmail size in bytes
injection_timestringWhen the email was queued for delivery
rcpt_metaobjectCustom 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

StatusErrorDescription
401UnauthorizedInvalid or missing API key
404Not FoundEmail with specified request ID not found
422Validation ErrorInvalid query parameters
500Server ErrorInternal 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