Skip to main content

Delivery Events

Sent, delivered, bounced

Opens

Track email opens

Clicks

Link click tracking

Complaints

Spam reports

​
Get Email Events

GET/v1/events
Retrieve email events including delivery confirmations, opens, clicks, bounces, and complaints. Useful for tracking engagement and debugging delivery issues.

​
Query Parameters

​
email_id
string
Filter events for a specific email
​
event_type
string
Filter by type: sent, delivered, opened, clicked, bounced, complained
​
days
number
default:"7"
Number of days to look back (1-90)
​
limit
number
default:"50"
Number of results (1-100)
​
offset
number
default:"0"
Pagination offset

​
Request

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

FieldTypeDescription
idstringUnique event identifier
email_idstringID of the associated email
typestringEvent type (see table below)
metadataobjectAdditional event data (varies by type)
created_atstringWhen the event occurred (ISO 8601)
emailobjectAssociated email info (to, subject)

​
Event Types

TypeDescriptionMetadata
sentEmail was sent to the mail servermessage_id
deliveredEmail was successfully deliveredsmtp_response
openedRecipient opened the emailuser_agent, ip_address
clickedRecipient clicked a linkurl, user_agent
bouncedEmail bounced (hard or soft)bounce_type, reason
complainedRecipient marked as spamcomplaint_type
unsubscribedRecipient unsubscribed—

​
Example Queries

​
Get all opens

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 "https://www.unosend.co/api/v1/events?email_id=email_abc123" \
  -H "Authorization: Bearer un_your_api_key"

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 "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
Use the Events API for analytics and reporting. Use Webhooks for real-time automation and triggers.