Skip to main content

​
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

ParameterTypeDefaultDescription
typestring—Filter by event type: Delivery, Bounce, Complaint, or Suppression
limitinteger50Results per page. Max 100
pageinteger1Page 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

FieldDescription
idUnique event ID
email_idID of the send this event belongs to. Use with GET /api/v1/send/:id/status to get the full send record
event_typeType of event — see event types
event_timestampWhen the event occurred
recipientThe specific email address this event applies to
bounce_typePresent on Bounce events. Permanent or Transient
bounce_subtypePresent on Bounce events. SES bounce subtype (e.g. General, NoEmail)
complaint_typePresent on Complaint events. ISP feedback type (e.g. abuse, fraud)

​
Event types

TypeDescription
DeliveryEmail was accepted by the recipient’s mail server
BounceEmail was rejected. Permanent bounces (hard bounces) automatically add the address to suppression. Transient bounces are temporary failures
ComplaintRecipient filed a spam complaint. Address is automatically added to suppression
SuppressionRecipient 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"