API Reference
Logs
Retrieve email delivery logs and activity history for debugging and monitoring. View detailed information about each email sent.
Email History
View all sent emails
Search
Find by recipient or subject
Filter
By status or date
Event Timeline
Track delivery events
GET
/v1/logsGet Email Logs
Retrieve a list of email logs with delivery status, events, and metadata. Logs include all email activity within the specified time range.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: sent, delivered, bounced, failed |
email_id | string | Filter logs for a specific email ID |
days | number | Number of days to look back (1-90). Default: 7 |
limit | number | Number of results (1-100). Default: 50 |
offset | number | Pagination offset. Default: 0 |
search | string | Search by subject or recipient email |
Request
cURL
curl "https://www.unosend.co/api/v1/logs?days=7&limit=50" \
-H "Authorization: Bearer un_your_api_key"Response
200 OK
{
"success": true,
"data": {
"data": [
{
"id": "email_abc123",
"from": "hello@yourcompany.com",
"to": ["user@example.com"],
"subject": "Welcome to our platform",
"status": "delivered",
"created_at": "2024-12-01T10:30:00.000Z",
"sent_at": "2024-12-01T10:30:01.000Z",
"delivered_at": "2024-12-01T10:30:03.000Z",
"scheduled_for": null,
"metadata": {
"user_id": "usr_123"
},
"events": [
{
"type": "sent",
"created_at": "2024-12-01T10:30:01.000Z",
"metadata": {}
},
{
"type": "delivered",
"created_at": "2024-12-01T10:30:03.000Z",
"metadata": {
"smtp_response": "250 OK"
}
}
]
}
],
"pagination": {
"total": 156,
"limit": 50,
"offset": 0,
"has_more": true
},
"filters": {
"status": null,
"days": 7,
"search": null
}
}
}Log Object Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique email identifier |
from | string | Sender email address |
to | array | Array of recipient email addresses |
subject | string | Email subject line |
status | string | Current status (sent, delivered, bounced, failed) |
created_at | string | When the email was created (ISO 8601) |
sent_at | string | null | When the email was sent |
delivered_at | string | null | When the email was delivered |
metadata | object | Custom metadata attached to the email |
events | array | Timeline of events for this email |
Status Values
| Status | Description |
|---|---|
| queued | Email is queued for sending |
| sent | Email has been sent to the mail server |
| delivered | Email was successfully delivered |
| bounced | Email bounced (hard or soft bounce) |
| failed | Email failed to send |
| scheduled | Email is scheduled for future delivery |
Example Queries
Filter by status
cURL
# Get only bounced emails
curl "https://www.unosend.co/api/v1/logs?status=bounced&days=30" \
-H "Authorization: Bearer un_your_api_key"Get logs for specific email
cURL
curl "https://www.unosend.co/api/v1/logs?email_id=email_abc123" \
-H "Authorization: Bearer un_your_api_key"Search by recipient
cURL
curl "https://www.unosend.co/api/v1/logs?search=user@example.com" \
-H "Authorization: Bearer un_your_api_key"Paginate through results
cURL
# Get second page of results
curl "https://www.unosend.co/api/v1/logs?limit=50&offset=50" \
-H "Authorization: Bearer un_your_api_key"