API Reference
Events
The Events API allows you to retrieve a comprehensive list of all email events across your team.
Base URL
https://api.unsent.dev/v1/eventsOverview
The Events API provides access to the raw firehose of email events. Unlike the Activity API which focuses on recent feed-like data, the Events API allows for more granular filtering by status and date range, making it suitable for reconciliation and reporting.
Features
Event History
Filterable history of all email status changes
Endpoints
Get All Events
GET /v1/events
Retrieve a paginated list of email events, optionally filtered by status and date.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | number | No | 1 | Page number |
limit | number | No | 50 | Results per page (max 100) |
status | string | No | - | Filter by status (e.g., BOUNCED, DELIVERED) |
startDate | string | No | - | Filter events occurring after this date (ISO 8601) |
Example Request:
curl -X GET "https://api.unsent.dev/v1/events?status=BOUNCED&limit=20" \
-H "Authorization: Bearer your-api-key"Response (200 OK):
{
"events": [
{
"id": "evt_abc123",
"emailId": "email_xyz789",
"status": "BOUNCED",
"data": {
"reason": "Mailbox unavailable"
},
"teamId": "team_123",
"createdAt": "2024-01-15T14:30:00Z"
}
],
"page": 1,
"limit": 20
}Error Responses:
- 400 Bad Request - Invalid filters or pagination
- 401 Unauthorized - API key is missing or invalid
- 429 Too Many Requests - Rate limit exceeded
- 500 Internal Server Error - Server error