---
title: "List email sends"
method: GET
path: "/v1/email-sends"
tags: ["Email"]
---

# List email sends

`GET /v1/email-sends`

## Request

- Base URL: `https://api-eu.dynamicdocumentapi.com`
- URL: `https://api-eu.dynamicdocumentapi.com/v1/email-sends`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Newest first; sends are kept for 30 days. Test keys see test sends only.

## Query parameters

- `batch_id` string
- `connection_id` string
- `created_after` string, date-time
- `cursor` string
- `limit` integer
- `render_id` string
- `rule_id` string
- `status` 'canceled' | 'failed' | 'pending' | 'retrying' | 'sandboxed' | 'sending' | 'sent' | 'skipped' | 'unknown'
- `template_id` string

## Response `200`

- EmailSendList
  - `data` EmailSend[], required
    - `attachments` EmailSendAttachment[], required
      - `bytes` integer, required
      - `file_id` string, required
      - `filename` string, required
      - `mode` 'attached' | 'linked', required: `linked`: a download link valid until the file's retention ends, at most 7 days.
    - `attempts` integer, required
    - `batch_id` string, nullable, required
    - `bcc_count` integer, required
    - `cc_count` integer, required
    - `connection_id` string, required
    - `created_at` string, date-time, required
    - `delivery` EmailDeliveryCounts, required: The recipients' delivery events, by kind: only Brevo reports them, so other providers' sends show zeros. `bounced` counts soft and hard bounces.
      - `blocked` integer, required
      - `bounced` integer, required
      - `complained` integer, required
      - `deferred` integer, required
      - `delivered` integer, required
      - `invalid` integer, required
    - `error` EmailSendError, required: Why a send failed or waits: never message bodies or addresses.
      - `code` string, required: `email_template_error`, `email_too_large`, `email_recipient_missing`, `email_address_invalid`, `email_too_many_recipients`, `email_attachment_too_large`, `email_attachment_type_not_allowed`, `email_needs_hosted_file`, `email_provider_rejected`, `email_provider_auth_failed`, `email_provider_unavailable`, `email_ip_not_authorized`, `email_rate_limited`, `email_outcome_unknown`, `email_daily_cap_reached`, `email_disabled`, `email_credentials_removed`, `email_send_expired`, `internal_error`
      - `column` integer
      - `field` string: `email_template_error`, `email_too_large`: the rule field, e.g. `subject`.
      - `line` integer: `email_template_error`: where in the field.
      - `message` string, required
      - `provider_code` string, nullable: The provider's own error code.
      - `provider_status` integer, nullable: The provider's HTTP or SMTP status.
    - `id` string, required
    - `mode` 'live' | 'sandbox' | 'redirect' | 'skip', required: `live`; for test renders the connection's `test_mode` (`sandbox`, `redirect`, `skip`); `redirect` for a rule test.
    - `object` 'email_send', required
    - `provider` 'brevo' | 'smtp' | 'postmark' | 'resend' | 'ses' | 'graph', required
    - `provider_message_id` string, nullable, required: The provider's id of the message; for SMTP the `Message-ID` we set. Microsoft 365 (`graph`) returns none.
    - `render_id` string, required
    - `resend_of` string, nullable, required: The send this one repeats (`ems_…`).
    - `rule_id` string, required
    - `sandbox` boolean, required: Sent with Brevo's sandbox header: nothing is delivered.
    - `sent_at` string, date-time, nullable, required
    - `skip_reason` 'condition_false' | 'test_mode', nullable, required
    - `status` 'pending' | 'sending' | 'retrying' | 'sent' | 'sandboxed' | 'skipped' | 'failed' | 'unknown' | 'canceled', required: `unknown`: the provider may have delivered it (e.g. a timeout after sending); it is never retried automatically: check the provider's logs (the message carries `X-Dda-Send-Id`) before resending.
    - `subject` string, nullable, required
    - `template_id` string, nullable, required
    - `test` boolean, required
    - `to` string[], required
  - `has_more` boolean, required
  - `next_cursor` string, nullable
  - `object` 'list', required

## Other responses

- `400`: Malformed id, unknown `status` or invalid `created_after`.
- `401`: Missing, invalid, expired or revoked credentials.
- `403`: Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified.
- `429`: Rate limited (`Retry-After`).

---

[API](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api.md) · [All operations](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/revisions/0f14bc0000f4?raw)