# Retrieve a batch of emails (/docs/api-reference/emails/get-email-batch)

A batch sent with `POST /v1/emails/batch`, with its emails' current statuses in the order of the request. Emails past the data retention period are left out. Only batches sent from the API key's own environment can be retrieved.

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

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 batch's id (`batch_id` of its emails).

## 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.getBatch("batch_01k8d0n6x5f3w2e1r9t7y4u6i8");
```

HTTP:

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

Python:

```python
from coss import Coss

client = Coss()  # api_key= or COSS_API_KEY

client.email.get_batch(
    id="batch_01k8d0n6x5f3w2e1r9t7y4u6i8",
)
```

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.GetBatchEmailRequest{
    ID: "batch_01k8d0n6x5f3w2e1r9t7y4u6i8",
}
client.Email.GetBatch(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

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

client.email.get_batch(id: "batch_01k8d0n6x5f3w2e1r9t7y4u6i8")
```

PHP:

```php
<?php

use Coss\Coss;

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

$client->email->getBatch(
    'batch_01k8d0n6x5f3w2e1r9t7y4u6i8',
);
```

Java:

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

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

client.email().getBatch(
    "batch_01k8d0n6x5f3w2e1r9t7y4u6i8",
    GetBatchEmailRequest
        .builder()
        .build()
);
```

.NET:

```csharp
using Coss;

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

await client.Email.GetBatchAsync(
    new GetBatchEmailRequest { Id = "batch_01k8d0n6x5f3w2e1r9t7y4u6i8" }
);
```

## Response 200

The batch.

- `object` ("email_batch", required)
- `id` (string, required)
- `data` (object[], required): The batch's emails, in the order of the request.
  - `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`.
- `created_at` (string, required, date-time)

Example:

```json
{
  "object": "email_batch",
  "id": "batch_01k8d0n6x5f3w2e1r9t7y4u6i8",
  "data": [
    {
      "object": "email",
      "id": "email_01k7c8m4q2f3e9v6t5r1n0p8yz",
      "from": "Acme <notifications@acme.com>",
      "to": [
        "ada@example.com"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "subject": "Your weekly summary",
      "html": "<p>Hi Ada, here is your week.</p>",
      "text": null,
      "headers": {},
      "tags": [],
      "category": "digest",
      "stream": "transactional",
      "status": "queued",
      "failure": null,
      "recipients": [
        {
          "address": "ada@example.com",
          "type": "to",
          "status": "queued",
          "last_event_at": null
        }
      ],
      "sandbox": false,
      "tracking": {
        "opens": false,
        "clicks": false,
        "unsubscribe": false,
        "open_count": 0,
        "first_opened_at": null,
        "last_opened_at": null,
        "click_count": 0,
        "first_clicked_at": null,
        "last_clicked_at": null
      },
      "attachments": [],
      "created_at": "2026-10-10T12:00:00.000Z",
      "sent_at": null,
      "scheduled_at": null,
      "batch_id": "batch_01k8d0n6x5f3w2e1r9t7y4u6i8",
      "template": null,
      "broadcast_id": null,
      "subaccount_id": null,
      "content_storage": {
        "mode": "store",
        "discarded_at": null
      }
    }
  ],
  "created_at": "2026-10-10T12:00:00.000Z"
}
```

## 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 batch 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`).