> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Query delivery events for your sends

# 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:**

```bash theme={null}
curl "https://api.numonic.com/api/v1/events" \
  -H "Authorization: Bearer YOUR_JWT"
```

**Filtered by type:**

```bash theme={null}
curl "https://api.numonic.com/api/v1/events?type=Bounce" \
  -H "Authorization: Bearer YOUR_JWT"
```

**Paginated:**

```bash theme={null}
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`

```json theme={null}
{
  "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-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:

```bash theme={null}
# 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"
```