# List a broadcast's emails (/docs/api-reference/broadcasts/list-broadcast-emails)

The emails made so far, one per contact, newest first.

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

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 broadcast's id.

## Query parameters

- `limit` (integer, 1-100): 1-100, default 50.
- `after` (string): Cursor: the `id` of the last email 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.broadcasts.listEmails("bcast_01k7c8m4q2f3e9v6t5r1n0p8yz");
```

HTTP:

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

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.email.broadcasts.list_emails(
    id="bcast_01k7c8m4q2f3e9v6t5r1n0p8yz",
)
```

Go:

```go
import (
	"context"

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

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

request := &email.ListEmailsBroadcastsRequest{
    ID: "bcast_01k7c8m4q2f3e9v6t5r1n0p8yz",
}
client.Email.Broadcasts.ListEmails(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

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

client.email.broadcasts.list_emails(id: "bcast_01k7c8m4q2f3e9v6t5r1n0p8yz")
```

PHP:

```php
<?php

use Coss\Coss;
use Coss\Email\Broadcasts\Requests\ListEmailsBroadcastsRequest;

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

$client->email->broadcasts->listEmails(
    'bcast_01k7c8m4q2f3e9v6t5r1n0p8yz',
    new ListEmailsBroadcastsRequest([]),
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.email.broadcasts.requests.ListEmailsBroadcastsRequest;

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

client.email().broadcasts().listEmails(
    "bcast_01k7c8m4q2f3e9v6t5r1n0p8yz",
    ListEmailsBroadcastsRequest
        .builder()
        .build()
);
```

.NET:

```csharp
using Coss;
using Coss.Email;

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

await client.Email.Broadcasts.ListEmailsAsync(
    new ListEmailsBroadcastsRequest { Id = "bcast_01k7c8m4q2f3e9v6t5r1n0p8yz" }
);
```

## Response 200

A page of emails.

- `object` ("list", required)
- `data` (object[], required)
  - `object` ("email", required)
  - `id` (string, required)
  - `from` (string, required): Who it's sent from.
  - `to` (string[], required): The `To` addresses.
  - `cc` (string[], required): The `Cc` addresses.
  - `bcc` (string[], required): The `Bcc` addresses.
  - `reply_to` (string[], required): The `Reply-To` addresses.
  - `subject` (string, required): The subject, rendered if it came from a template.
  - `html` (string | null, required): The HTML part. `null`: none, or the body was discarded.
  - `text` (string | null, required): The plain text part. `null`: none, or the body was discarded.
  - `headers` (map of string, required): The custom headers it was sent with.
  - `tags` (object[], required): Your tags on the email.
    - `name` (string, required): The tag's name.
    - `value` (string, required): The tag's value.
  - `category` (string | null, required): The email's category, which suppressions and tracking rules can scope to. `null`: none.
  - `stream` ("transactional" | "marketing", required): `transactional` or `marketing`.
  - `status` ("queued" | "sent" | "failed" | "scheduled" | "canceled", required): Whether the email was handed to the delivery provider. `scheduled` emails wait for `scheduled_at`; `canceled` ones were canceled before that. Per-recipient delivery is in `recipients`.
  - `failure` (object | null, required): Why the email failed; `null` unless `status` is `failed`.
    - `code` (string, required): Why the email failed, e.g. `all_recipients_suppressed`, `domain_not_verified`, `content_rejected`, `attachments_unavailable`, `dispatch_failed` or `provider_error`.
    - `message` (string, required)
  - `recipients` (object[], required): Each recipient, with how delivery to them went.
    - `address` (string, required): The bare, lower-cased address.
    - `type` ("to" | "cc" | "bcc", required): Which list it's on: `to`, `cc` or `bcc`.
    - `status` ("queued" | "sent" | "delivery_delayed" | "delivered" | "bounced" | "suppressed" | "complained" | "failed" | "canceled", required): Delivery status of this recipient. `suppressed` means the address is on the environment's suppression list (for every email or for this email's category), so it was skipped. `canceled` means the scheduled email was canceled before it was sent.
    - `last_event_at` (string | null, required, date-time): When its latest delivery event happened. `null`: none yet.
  - `attachments` (object[], required): Attachment metadata. Content is never returned, and is discarded once sent.
    - `id` (string, required)
    - `filename` (string, required)
    - `content_type` (string, required)
    - `content_id` (string | null, required): Set for inline attachments (`cid:` references).
    - `size` (integer, required): Size in bytes.
  - `sandbox` (boolean, required): True when sent from a sandbox environment (never delivered).
  - `tracking` (object, required): Open and click tracking, as resolved when the email was sent, with engagement so far. Opens can be inflated by mail clients that prefetch images, clicks by link scanners.
    - `opens` (boolean, required): Whether opens are tracked for this email.
    - `clicks` (boolean, required): Whether link clicks are tracked for this email.
    - `unsubscribe` (boolean, required): Whether the email carries one-click unsubscribe headers (RFC 8058).
    - `open_count` (integer, required): Times opened. Mail clients that prefetch images inflate it.
    - `first_opened_at` (string | null, required, date-time): When it was first opened. `null`: not yet.
    - `last_opened_at` (string | null, required, date-time): When it was last opened. `null`: not yet.
    - `click_count` (integer, required): Link clicks. Link scanners inflate it.
    - `first_clicked_at` (string | null, required, date-time): When a link was first clicked. `null`: not yet.
    - `last_clicked_at` (string | null, required, date-time): When a link was last clicked. `null`: not yet.
  - `created_at` (string, required, date-time)
  - `sent_at` (string | null, required, date-time): When it was handed to the provider. `null`: not yet.
  - `scheduled_at` (string | null, required, date-time): When the email was scheduled to be sent; `null` if it was not.
  - `batch_id` (string | null, required): The batch that sent the email; `null` if it was sent on its own.
  - `template` (object | null, required): The template the email was rendered from; `null` if it was sent without one.
    - `id` (string, required): The template's id.
    - `version` (integer | null, required): `null` for a dashboard test send of the draft.
    - `locale` (string, required): The locale the email was rendered in.
  - `broadcast_id` (string | null, required): The broadcast the email is part of; `null` for any other email.
  - `subaccount_id` (string | null, required): The sub-account the email was sent for; `null` if it was sent for none.
  - `content_storage` (object, required): Whether coss.com keeps the email's content after sending it.
    - `mode` ("store" | "discard", required): The environment's content storage when the email was sent. With `discard`, the subject, `html`, `text`, `headers`, template variables and attachment filenames are cleared once the email is sent, fails or is canceled.
    - `discarded_at` (string | null, required, date-time): When the content was cleared; `null` while it is kept. A cleared email has an empty `subject`, `html` and `text` `null` and no `headers`.
- `has_more` (boolean, required)

## 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 broadcast with this id exists in the API key's environment (`not_found`).
- `422`: A query parameter failed validation (`validation_error`, see `issues`).
- `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`).