---
title: "List sent emails"
method: GET
path: "/companies/{company}/emails"
tags: ["Emails"]
---

# List sent emails

`GET /companies/{company}/emails`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/emails`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

List the emails your company sent through the platform, newest first (invoices, quotes, pro formas, delivery notes, reminders).
- `status` describes the hand-off to the outgoing SMTP server, not real delivery.
- `sent` does not mean the recipient received it.

## Path parameters

- `company` string, uuid, required

## Query parameters

- `status` 'queued' | 'sending' | 'sent' | 'failed'
- `recipient_email` string
- `related_entity_id` string, uuid
- `related_entity_type` 'invoice' | 'quote' | 'proforma' | 'delivery_note' | 'purchase_invoice' | 'recurring_invoice'
- `created_at[gte]` string, date-time
- `created_at[lte]` string, date-time
- `search` string
- `limit` integer
- `starting_after` string

## Headers

- `Factuarea-Version` string, date

## Response `200`

`EmailDeliveryListV1Resource`

- object: Cursor-paginated page of sent emails (`{ data, has_more, next_cursor }`), most recent first.
  - `data` object[], required: Page of sent emails, newest first.
    - `id` string, uuid, required: UUID v7 of the send. Use it in `GET /v1/companies/{company}/emails/{email}`.
    - `object` 'email_delivery', required: Always `email_delivery`.
    - `recipient_email` string, email, required: Address the message was sent to.
    - `cc` string[], required: Addresses in copy. Empty array when there were none.
    - `bcc` string[], required: Addresses in blind copy. Empty array when there were none.
    - `subject` string, required: Subject line of the message.
    - `status` 'queued' | 'sending' | 'sent' | 'failed', required: Status of the send. It describes the hand-off to the OUTGOING SMTP SERVER, NOT real delivery to the recipient's mailbox: `queued` (accepted, waiting for the worker), `sending` (being handed off), `sent` (the outgoing mail server accepted the message) and `failed` (every attempt failed). A `sent` message can still bounce or land in spam afterwards without the platform finding out. There are deliberately no `delivered`, `bounced` or `opened` values: observing them would require a mail provider with delivery webhooks, which is out of scope.
    - `attempts` integer, required: Number of hand-off attempts made for this message.
    - `error_message` string, nullable, required: Error reported by the outgoing mail server on the last failed attempt, or `null` when there was none.
    - `sent_at` string, date-time, nullable, required: When the outgoing mail server accepted the message (ISO 8601), or `null` if it never did. It marks the hand-off, not a confirmed delivery or a read.
    - `failed_at` string, date-time, nullable, required: When the last attempt failed (ISO 8601), or `null` when none failed.
    - `created_at` string, date-time, nullable, required: When the send was registered (ISO 8601).
    - `related_entity_type` 'invoice' | 'quote' | 'proforma' | 'delivery_note' | 'purchase_invoice' | 'recurring_invoice' | 'null', nullable, required: Type of the document the email was sent for, or `null` for non-document emails (test messages, account emails).
    - `related_entity_id` string, uuid, nullable, required: UUID v7 of the related document, or `null` for non-document emails and for older rows recorded before the sender stored it.
  - `has_more` boolean, required: `true` when more emails exist beyond this page.
  - `next_cursor` string, nullable, required: Opaque cursor to pass as `starting_after` for the next page, or `null` when `has_more` is `false`. Unlike the rest of the v1 listings it is a numeric string, not a UUID v7 — treat it as opaque and reuse it verbatim.

## Other responses

- `400`: The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)