> ## 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. # Email History > Query your Lettr email history through the API to check delivery status, view recipient details, and audit past sending activity 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: ```bash theme={null} 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 ```json theme={null} { "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 ", "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: ```bash theme={null} 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: ```javascript theme={null} const result = await lettr.emails.send({ from: 'you@example.com', to: ['recipient@example.com'], subject: 'Hello', html: '

Message content

' }); // Store the request_id for later lookup const requestId = result.data.request_id; ``` ### Response ```json theme={null} { "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 ", "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: ```javascript theme={null} // 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: ```bash theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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 | ## Related Topics Aggregate email performance metrics Real-time email event notifications Attach custom data to emails Prevent duplicate sends