Skip to main content
GET
/
emails
/
{request_id}
Get Request Details
curl --request GET \
  --url https://api.example.com/emails/{request_id}

​
Get Request Details

Retrieve detailed event information for a specific email sending request. This endpoint returns all events associated with a request, including delivery status, bounces, opens, clicks, and more.
​
request_id
string
required
The unique identifier of the email sending request (transmission ID).

​
Request

curl https://app.uselettr.com/api/emails/7582751837467401763 \
  -H "Authorization: Bearer le_xxxxxxxxxxxx"

​
Response

{
  "results": [
    {
      "request_id": "7582751837467401763",
      "message_id": "0001a2b3c4d5e6f7@mail.example.com",
      "event_id": "evt_abc123def456",
      "type": "delivery",
      "timestamp": "2024-01-15T10:30:05Z",
      "subject": "Welcome to Lettr!",
      "friendly_from": "John Doe <john@example.com>",
      "sending_domain": "mail.example.com",
      "click_tracking": true,
      "open_tracking": true,
      "rcpt_to": "recipient@gmail.com",
      "raw_rcpt_to": "Recipient Name <recipient@gmail.com>",
      "recipient_domain": "gmail.com",
      "mailbox_provider": "Gmail",
      "mailbox_provider_region": "US",
      "rcpt_meta": {
        "user_id": "user_123",
        "campaign": "welcome_series"
      },
      "sending_ip": "192.168.1.100",
      "reason": null,
      "raw_reason": null,
      "error_code": null,
      "transactional": true,
      "msg_size": 15234,
      "injection_time": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 1
}

​
Response Fields

​
Event Object

FieldTypeDescription
request_idstringThe transmission/request identifier
message_idstring | nullThe unique message identifier
event_idstringUnique identifier for this event
typestringThe event type (see Event Types below)
timestampstringISO 8601 timestamp of the event
subjectstring | nullEmail subject line
friendly_fromstring | nullSender display name and address
sending_domainstring | nullDomain used for sending
click_trackingboolean | nullWhether click tracking is enabled
open_trackingboolean | nullWhether open tracking is enabled
rcpt_tostringRecipient email address
raw_rcpt_tostringRaw recipient with display name
recipient_domainstringDomain of the recipient
mailbox_providerstringDetected mailbox provider (e.g., Gmail, Outlook)
mailbox_provider_regionstringGeographic region of the mailbox provider
rcpt_metaobjectCustom metadata attached to the recipient
sending_ipstring | nullIP address used for sending
reasonstring | nullHuman-readable reason for bounces/failures
raw_reasonstring | nullRaw SMTP response or error message
error_codestring | nullError code for failed deliveries
transactionalbooleanWhether the email was marked as transactional
msg_sizeinteger | nullSize of the message in bytes
injection_timestring | nullISO 8601 timestamp when email was injected

​
Event Types

TypeDescription
injectionEmail was received and queued for delivery
deliveryEmail was successfully delivered
bounceEmail bounced (hard or soft bounce)
out_of_bandAsynchronous bounce received after initial delivery
policy_rejectionEmail rejected due to policy
delayDelivery was delayed
openRecipient opened the email
initial_openFirst open by recipient
clickRecipient clicked a link
spam_complaintRecipient marked email as spam
list_unsubscribeRecipient used list-unsubscribe header
link_unsubscribeRecipient clicked unsubscribe link

​
Example: Bounce Event

{
  "results": [
    {
      "request_id": "7582751837467401763",
      "message_id": null,
      "event_id": "evt_xyz789",
      "type": "bounce",
      "timestamp": "2024-01-15T10:30:10Z",
      "subject": "Welcome to Lettr!",
      "friendly_from": "John Doe <john@example.com>",
      "sending_domain": "mail.example.com",
      "click_tracking": true,
      "open_tracking": true,
      "rcpt_to": "invalid@example.com",
      "raw_rcpt_to": "invalid@example.com",
      "recipient_domain": "example.com",
      "mailbox_provider": "Unknown",
      "mailbox_provider_region": "Unknown",
      "rcpt_meta": {},
      "sending_ip": "192.168.1.100",
      "reason": "Invalid recipient",
      "raw_reason": "550 5.1.1 The email account that you tried to reach does not exist",
      "error_code": "550",
      "transactional": true,
      "msg_size": 15234,
      "injection_time": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 1
}

​
Multiple Recipients

When sending to multiple recipients in a single request, each recipient will have their own event entries: 
{
  "results": [
    {
      "request_id": "7582751837467401763",
      "event_id": "evt_001",
      "type": "delivery",
      "rcpt_to": "user1@gmail.com",
      "mailbox_provider": "Gmail",
      "timestamp": "2024-01-15T10:30:05Z"
    },
    {
      "request_id": "7582751837467401763",
      "event_id": "evt_002",
      "type": "delivery",
      "rcpt_to": "user2@outlook.com",
      "mailbox_provider": "Microsoft",
      "timestamp": "2024-01-15T10:30:06Z"
    },
    {
      "request_id": "7582751837467401763",
      "event_id": "evt_003",
      "type": "bounce",
      "rcpt_to": "invalid@example.com",
      "reason": "User unknown",
      "timestamp": "2024-01-15T10:30:07Z"
    }
  ],
  "total_count": 3
}

​
Errors

CodeDescription
not_foundRequest with specified ID not found
invalid_request_idThe provided request ID format is invalid