# List an email's delivery events (/docs/api-reference/emails/list-email-events)

Every delivery event of the email, oldest first: `email.scheduled`, `email.rescheduled`, `email.canceled`, `email.sent` and `email.failed` for the whole email, and `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained` and `email.suppressed` (skipped because of the suppression list) per recipient, plus `email.opened` and `email.clicked` when tracking is on (attributed to a recipient only when the email had a single one) and `email.unsubscribed` after a one-click unsubscribe.

`GET https://api.coss.com/v1/emails/{id}/events`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Path parameters

- `id` (string, required): The email's id.

## Query parameters

- `limit` (integer, 1-1000, default 1000)
- `after` (string): The last event id of the previous page.

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.email.listEvents("email_01k7c8m4q2f3e9v6t5r1n0p8yz");
```

HTTP:

```sh
curl -X GET "https://api.coss.com/v1/emails/email_01k7c8m4q2f3e9v6t5r1n0p8yz/events" \
  -H "Authorization: Bearer $COSS_API_KEY"
```

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.email.list_events(
    id="email_01k7c8m4q2f3e9v6t5r1n0p8yz",
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &coss.ListEventsEmailRequest{
    ID: "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
}
client.Email.ListEvents(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.email.list_events(id: "email_01k7c8m4q2f3e9v6t5r1n0p8yz")
```

PHP:

```php
<?php

use Coss\Coss;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->email->listEvents(
    'email_01k7c8m4q2f3e9v6t5r1n0p8yz',
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.email.requests.ListEventsEmailRequest;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.email().listEvents(
    "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
    ListEventsEmailRequest
        .builder()
        .build()
);
```

.NET:

```csharp
using Coss;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Email.ListEventsAsync(
    new ListEventsEmailRequest { Id = "email_01k7c8m4q2f3e9v6t5r1n0p8yz" }
);
```

## Response 200

The email's events.

- `object` ("list", required)
- `data` (object[], required)
  - `object` ("email_event", required)
  - `id` (string, required)
  - `email_id` (string, required): The email's id.
  - `type` ("email.sent" | "email.delivered" | "email.delivery_delayed" | "email.bounced" | "email.complained" | "email.failed" | "email.suppressed" | "email.scheduled" | "email.canceled" | "email.opened" | "email.clicked" | "email.rescheduled" | "email.unsubscribed", required): What happened, such as `email.delivered` or `email.bounced`.
  - `recipient` (string | null, required): The recipient this event is about; `null` for the whole email.
  - `occurred_at` (string, required, date-time): When it happened.
  - `data` (object, required): Details of the event: only what its `type` has.
    - `bounce` (object)
      - `type` ("permanent" | "transient" | "undetermined", required): `permanent`, `transient` or `undetermined`.
      - `sub_type` (string, required): The provider's finer classification of the bounce.
      - `diagnostic_code` (string | null, required): What the receiving server answered. `null`: not reported.
    - `complaint` (object)
      - `feedback_type` (string | null, required): The kind of complaint the mailbox provider reported. `null`: not reported.
      - `sub_type` (string | null, required): The provider's finer classification. `null`: not reported.
    - `delay` (object)
      - `type` (string, required): The provider's reason for the delay.
      - `expires_at` (string | null, required, date-time): When the provider stops trying. `null`: not reported.
      - `diagnostic_code` (string | null, required): What the receiving server answered. `null`: not reported.
    - `delivery` (object)
      - `smtp_response` (string | null, required): What the receiving server answered. `null`: not reported.
    - `failure` (object)
      - `code` (string, required): Machine-readable reason.
      - `message` (string, required): Human-readable explanation.
    - `suppression` (object): Only for `email.suppressed`: the entry that matched the recipient.
      - `id` (string, required): The suppression's id.
      - `scope` (string, required): What it covers: every email, every marketing email, or one category.
      - `reason` ("bounce" | "complaint" | "manual" | "import" | "unsubscribe", required): `bounce`: added after a permanent bounce. `complaint`: added after a spam complaint. `manual`: added one by one through the API or dashboard. `import`: added by a bulk import. `unsubscribe`: added by the recipient's one-click unsubscribe, scoped to the email's category.
    - `unsubscribe` (object): Only for `email.suppressed` without `suppression`: the recipient is a contact who unsubscribed (from marketing, or from the email's topic, `topic`).
      - `contact_id` (string | null, required): The contact who unsubscribed. `null`: none.
      - `topic` (string | null, required): The topic they left. `null`: marketing altogether.
    - `open` (object): Only for `email.opened`.
      - `user_agent` (string | null, required): The client's `User-Agent`. `null`: not sent.
    - `click` (object): Only for `email.clicked`.
      - `url` (string, required): The original link that was clicked.
      - `link_position` (integer, required): Index of the link among the email's tracked links.
      - `user_agent` (string | null, required): The client's `User-Agent`. `null`: not sent.
    - `reschedule` (object): Only for `email.rescheduled`.
      - `scheduled_at` (string, required, date-time): The new time.
      - `previous_scheduled_at` (string, required, date-time): The time it replaced.
- `has_more` (boolean, required)

Example:

```json
{
  "object": "list",
  "data": [
    {
      "object": "email_event",
      "id": "evt_01k7c8m4r0c2b8w9y3d5f6g7h8",
      "email_id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
      "type": "email.sent",
      "recipient": null,
      "occurred_at": "2026-10-10T12:00:01.000Z",
      "data": {}
    },
    {
      "object": "email_event",
      "id": "evt_01k7c8m4q2f3e9v6t5r1n0p8yz",
      "email_id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
      "type": "email.delivered",
      "recipient": "user@example.com",
      "occurred_at": "2026-10-10T12:00:02.000Z",
      "data": {
        "delivery": {
          "smtp_response": "250 2.0.0 OK"
        }
      }
    }
  ],
  "has_more": false
}
```

## Errors

- `400`: The `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `404`: No email with this id exists in the API key's environment (`not_found`).
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The API key could not be verified right now; retry (`service_unavailable`).