Events

Numonic ingests SES delivery events and makes them queryable. Every delivery, bounce, complaint, and suppression action is recorded as an event tied to the originating send ID. Events require JWT authentication.

List events

GET /api/v1/events

Returns delivery events for your account, newest first.

Request

All events:

curl "https://api.numonic.com/api/v1/events" \
  -H "Authorization: Bearer YOUR_JWT"

Filtered by type:

curl "https://api.numonic.com/api/v1/events?type=Bounce" \
  -H "Authorization: Bearer YOUR_JWT"

Paginated:

curl "https://api.numonic.com/api/v1/events?type=Complaint&page=1&limit=25" \
  -H "Authorization: Bearer YOUR_JWT"

Query parameters

Parameter	Type	Default	Description
`type`	string	—	Filter by event type: `Delivery`, `Bounce`, `Complaint`, or `Suppression`
`limit`	integer	`50`	Results per page. Max `100`
`page`	integer	`1`	Page number

Response `200`

{
  "success": true,
  "data": {
    "events": [
      {
        "id":              "550e8400-e29b-41d4-a716-446655440000",
        "email_id":        "550e8400-e29b-41d4-a716-446655440001",
        "event_type":      "Bounce",
        "event_timestamp": "2026-04-09T10:30:09.000Z",
        "recipient":       "user@example.com",
        "bounce_type":     "Permanent",
        "bounce_subtype":  "General"
      },
      {
        "id":              "550e8400-e29b-41d4-a716-446655440002",
        "email_id":        "550e8400-e29b-41d4-a716-446655440003",
        "event_type":      "Delivery",
        "event_timestamp": "2026-04-09T10:28:00.000Z",
        "recipient":       "other@example.com"
      }
    ],
    "pagination": {
      "page":        1,
      "limit":       50,
      "total":       150,
      "total_pages": 3
    }
  }
}

Event fields

Field	Description
`id`	Unique event ID
`email_id`	ID of the send this event belongs to. Use with `GET /api/v1/send/:id/status` to get the full send record
`event_type`	Type of event — see event types
`event_timestamp`	When the event occurred
`recipient`	The specific email address this event applies to
`bounce_type`	Present on `Bounce` events. `Permanent` or `Transient`
`bounce_subtype`	Present on `Bounce` events. SES bounce subtype (e.g. `General`, `NoEmail`)
`complaint_type`	Present on `Complaint` events. ISP feedback type (e.g. `abuse`, `fraud`)

Event types

Type	Description
`Delivery`	Email was accepted by the recipient’s mail server
`Bounce`	Email was rejected. `Permanent` bounces (hard bounces) automatically add the address to suppression. `Transient` bounces are temporary failures
`Complaint`	Recipient filed a spam complaint. Address is automatically added to suppression
`Suppression`	Recipient was on your suppression list and was filtered out before the send went out

Correlating events with sends

Each event’s email_id maps to the id returned when you created a send:

# Look up the full record for an email_id from an event
curl https://api.numonic.com/api/v1/send/550e8400-e29b-41d4-a716-446655440001/status \
  -H "X-API-Key: nmc_live_YOUR_API_KEY"

Getting Started

API Reference

Events

Events

List events

Request

Query parameters

Response `200`

Event fields

Event types

Correlating events with sends

​Events

​List events

​Request

​Query parameters

​Response 200

​Event fields

​Event types

​Correlating events with sends

Events

List events

Request

Query parameters

Response `200`

Event fields

Event types

Correlating events with sends