Skip to main content
GET
/
v1
/
emails
List Emails
curl --request GET \
  --url https://api.example.com/v1/emails

​
List Emails

Retrieve a list of emails with optional filtering.
​
limit
integer
default:"10"
Number of emails to return. Maximum 100.
​
starting_after
string
Cursor for pagination. Use the ID of the last email from the previous page.
​
ending_before
string
Cursor for pagination. Use the ID of the first email from the previous page.
​
status
string
Filter by status: queued, sent, delivered, bounced, failed.
​
to
string
Filter by recipient email address.
​
tags
string
Filter by tag (comma-separated for multiple).
​
from_date
string
Filter emails created after this ISO 8601 timestamp.
​
to_date
string
Filter emails created before this ISO 8601 timestamp.

​
Request

curl "https://api.lettr.dev/v1/emails?limit=10&status=delivered" \
  -H "Authorization: Bearer le_xxxxxxxxxxxx"

​
Response

{
  "object": "list",
  "data": [
    {
      "id": "email_123abc",
      "object": "email",
      "from": "you@example.com",
      "to": ["recipient@example.com"],
      "subject": "Hello World",
      "status": "delivered",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "email_456def",
      "object": "email",
      "from": "you@example.com",
      "to": ["another@example.com"],
      "subject": "Welcome",
      "status": "delivered",
      "createdAt": "2024-01-15T09:00:00Z"
    }
  ],
  "hasMore": true,
  "totalCount": 150
}

​
Pagination Example

// Fetch all emails using pagination
let allEmails = [];
let hasMore = true;
let cursor = null;

while (hasMore) {
  const response = await lettr.emails.list({
    limit: 100,
    starting_after: cursor
  });
  
  allEmails = allEmails.concat(response.data);
  hasMore = response.hasMore;
  
  if (response.data.length > 0) {
    cursor = response.data[response.data.length - 1].id;
  }
}