API Reference
Events
Retrieve webhook events and email activity history. Events track opens, clicks, bounces, and delivery status changes.
Delivery Events
Sent, delivered, bounced
Opens
Track email opens
Clicks
Link click tracking
Complaints
Spam reports
GET
/v1/eventsGet Email Events
Retrieve email events including delivery confirmations, opens, clicks, bounces, and complaints. Useful for tracking engagement and debugging delivery issues.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
email_id | string | Filter events for a specific email |
event_type | string | Filter by type: sent, delivered, opened, clicked, bounced, complained |
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 |
Request
cURL
curl "https://www.unosend.co/api/v1/events?days=7&limit=50" \
-H "Authorization: Bearer un_your_api_key"Response
200 OK
{
"success": true,
"data": {
"data": [
{
"id": "evt_abc123",
"email_id": "email_xyz789",
"type": "opened",
"metadata": {
"user_agent": "Mozilla/5.0...",
"ip_address": "192.168.1.1"
},
"created_at": "2024-12-01T14:30:00.000Z",
"email": {
"to": ["user@example.com"],
"subject": "Welcome to our platform"
}
},
{
"id": "evt_abc124",
"email_id": "email_xyz789",
"type": "clicked",
"metadata": {
"url": "https://example.com/activate",
"user_agent": "Mozilla/5.0..."
},
"created_at": "2024-12-01T14:32:00.000Z",
"email": {
"to": ["user@example.com"],
"subject": "Welcome to our platform"
}
}
],
"pagination": {
"total": 89,
"limit": 50,
"offset": 0,
"has_more": true
},
"filters": {
"email_id": null,
"event_type": null,
"days": 7
}
}
}Event Object Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique event identifier |
email_id | string | ID of the associated email |
type | string | Event type (see table below) |
metadata | object | Additional event data (varies by type) |
created_at | string | When the event occurred (ISO 8601) |
email | object | Associated email info (to, subject) |
Event Types
| Type | Description | Metadata |
|---|---|---|
| sent | Email was sent to the mail server | message_id |
| delivered | Email was successfully delivered | smtp_response |
| opened | Recipient opened the email | user_agent, ip_address |
| clicked | Recipient clicked a link | url, user_agent |
| bounced | Email bounced (hard or soft) | bounce_type, reason |
| complained | Recipient marked as spam | complaint_type |
| unsubscribed | Recipient unsubscribed | — |
Example Queries
Get all opens
cURL
curl "https://www.unosend.co/api/v1/events?event_type=opened&days=30" \
-H "Authorization: Bearer un_your_api_key"Get events for specific email
cURL
curl "https://www.unosend.co/api/v1/events?email_id=email_abc123" \
-H "Authorization: Bearer un_your_api_key"Get all link clicks
cURL
curl "https://www.unosend.co/api/v1/events?event_type=clicked&days=7" \
-H "Authorization: Bearer un_your_api_key"Get bounces for analysis
cURL
curl "https://www.unosend.co/api/v1/events?event_type=bounced&days=90&limit=100" \
-H "Authorization: Bearer un_your_api_key"Events API vs Webhooks
Events API (Pull)
- • Query historical events on demand
- • Good for analytics and reporting
- • Paginated results
- • Up to 90 days of history
Webhooks (Push)
- • Real-time event notifications
- • Good for triggers and automation
- • Requires endpoint setup
- • Events delivered as they happen