--- title: "List the email history" method: GET path: "/v1/emails" tags: ["Emails"] deprecated: true --- # List the email history `GET /v1/emails` ## Request - Base URL: `https://app.beel.es/api` - URL: `https://app.beel.es/api/v1/emails` - Auth: HTTP bearer > **Deprecated.** Returns the emails the system recorded on behalf of the authenticated account: invoice deliveries, verification, onboarding. It only reads the history; it does not send or resend anything. - **Deprecated:** use `GET /v1/accounts/{account_id}/emails`, which behaves identically. - **Every attempt is recorded**, not only the ones that went out: an email stopped by policy is listed with `status` `REJECTED`, and one accepted but not dispatched yet as `QUEUED`, rather than being omitted. - **Order:** by `sent_at` descending, configurable with `sort_by` / `sort_order`. - **Filters:** `type`, `status`, `recipient` and `related_entity_id`. - **`sent_at`:** the moment the message was handed over, so it is absent while an email is still `QUEUED`. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch. ## Query parameters - `page` integer - `limit` integer - `type` string - `status` 'QUEUED' | 'REJECTED' | 'SENT' | 'FAILED' | 'DELIVERED' | 'BOUNCED' | 'OPENED': Status of an email. The history records every email the system decided to send, not only the ones that went out: an email stopped by policy is listed as REJECTED rather than omitted. - QUEUED: authorised and recorded, not dispatched yet - REJECTED: stopped by policy and never sent (terminal, not retried). In test environments invoices may only be emailed to the account owner's own address (`+tag` aliases included), so a message addressed elsewhere lands here - SENT: successfully sent to the provider - FAILED: sending failed - DELIVERED / BOUNCED / OPENED: reported by the provider's webhooks - `recipient` string - `related_entity_id` string, uuid - `sort_by` 'sent_at' | 'status' | 'email_type': Email delivery field the list is ordered by: `sent_at` the instant of the attempt, `status` the delivery status, `email_type` the kind of email. - `sort_order` 'asc' | 'desc': Sort direction. Shared vocabulary for every `sort_order` query param: declared once so the generator emits a real enum and an unknown direction is rejected with `400` instead of being silently ignored. ## Response `200` Email history retrieved successfully - EmailDeliveryListResponse - `success` boolean, required - `data` object, required - `emails` EmailDeliveryResponse[], required - `id` string, uuid, required - `email_type` string, required: Email type (EmailType name or template). e.g. INVOICE_EMITTED - `recipients` string[], required: Recipient addresses (To) - `cc` string[]: Carbon-copy addresses (CC) - `subject` string - `related_entity_type` string, nullable: Type of the SINGLE related entity (e.g. INVOICE for an invoice, USER, SUBSCRIPTION). `null` for batch emails (BULK_INVOICES): their relation is the invoices in `related_invoices`, not a single entity. - `related_entity_id` string, uuid, nullable: Id of the single related entity. `null` for batch emails. - `status` 'QUEUED' | 'REJECTED' | 'SENT' | 'FAILED' | 'DELIVERED' | 'BOUNCED' | 'OPENED', required: Status of an email. The history records every email the system decided to send, not only the ones that went out: an email stopped by policy is listed as REJECTED rather than omitted. - QUEUED: authorised and recorded, not dispatched yet - REJECTED: stopped by policy and never sent (terminal, not retried). In test environments invoices may only be emailed to the account owner's own address (`+tag` aliases included), so a message addressed elsewhere lands here - SENT: successfully sent to the provider - FAILED: sending failed - DELIVERED / BOUNCED / OPENED: reported by the provider's webhooks - `sent_at` string, date-time: Time the email was sent - `pagination` Pagination - `current_page` integer, required - `total_pages` integer, required: How many pages the query has. An empty collection has **one** page — the first one, empty — so the smallest value a canonical route returns is `1`. The deprecated flat aliases (`/v1/invoices`, `/v1/customers`, …) answer `0` for that same empty collection, and `has_next`/`has_previous` follow suit. They were left as they were on purpose: a client that reads `total_pages == 0` as "no results" would break if it changed under it. Do not compare the two families of routes field by field; read `total_items` if what you want to know is whether anything came back. - `total_items` integer, required - `items_per_page` integer, required - `has_next` boolean - `has_previous` boolean - `meta` ResponseMeta - `timestamp` string, date-time - `request_id` string ## Other responses - `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. - `403`: Authenticated but not allowed. Fourteen causes shared by every operation, told apart by `error.code`; an operation that adds a cause of its own names it in its `403`. You can branch on them exhaustively. - `INSUFFICIENT_SCOPE` — the credential lacks a scope the operation requires; `error.details.missing_scopes` names them as a single comma-separated string (for example `"invoices:write,customers:read"`), not as an array; `required_scopes` has the same shape and lists every scope the operation needs. Retrying will not help: mint a key that holds them. - `COMPANY_READ_ONLY` — the scope is there, but your access level over that NIF only lets you read it. - `ACCOUNT_MANAGEMENT_FORBIDDEN` — the scope is there, but your role over the account, or the management relationship you hold over it, does not cover this operation. - `ACCOUNT_NOT_ACCESSIBLE` — the account is not yours to reach, which is also the answer when it does not exist, so existence is never disclosed. - `ACTIVE_COMPANY_NOT_ACCESSIBLE` — the same, for a NIF: the company in the path, or the one named by `BeeL-Active-Company`, is not one this credential may reach — and again, this is also the answer when it does not exist. - `COMPANY_ACCESS_REVOKED` — your access to the NIF was withdrawn while the request was already in flight, so the write was rejected and nothing was recorded. Retrying will not help until the access is granted again. - `LIVE_CREDENTIAL_REQUIRED` — the operation changes the real account and the call came from a test API key (`beel_sk_test_…`). Use your live key or the dashboard. - `FEATURE_NOT_AVAILABLE` — your subscription does not include the entitlement the operation needs; `error.details.feature_code` names it. This gate runs **before** the scope gate, so for such an operation you never see `INSUFFICIENT_SCOPE` first. - `NO_ACTIVE_ACCOUNT` — the credential does not resolve to an account, so no scope can be evaluated against one. Fail-closed, not a permission that can be granted to you. - `OPERATION_REQUIRES_SESSION` — the operation is available only from the web session; no API key and no OAuth2 token can perform it, whatever scopes it holds. - `OPERATION_REQUIRES_API_KEY` — the reverse: the operation needs a scope that only an API key can hold (such as `accounts:write`), so a dashboard session never satisfies it. - `API_KEY_LIVE_NOT_AVAILABLE` — the call came with a live API key (`beel_sk_live_…`) and the account has no Live mode yet. It is never degraded to Test: use your test key, or activate Live first. - `ACCOUNT_REQUIRES_FOCUS_SWITCH` — dashboard session only: you are a member of the account in the path, but it is not the account in focus. Switch focus to it and retry. - `REQUEST_BLOCKED` — the edge security filter stopped the request before the API saw its body, usually because a text field carries something that looks like markup or a script (HTML tags, `