Emails

List the email history

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 for what moved where and what changes when you switch.

get/v1/emails

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/emails
  • Auth: HTTP bearer

Query parameters

pageinteger

Page number, starting at 1. The response echoes it back as pagination.current_page.

limitinteger

How many items to return per page. The response echoes it back as pagination.items_per_page.

typestring

Filter by email type (e.g. INVOICE_EMITTED)

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

Filter by delivery status

recipientstring

Filter to emails where any recipient contains the term (case-insensitive)

related_entity_idstring uuid

Filter to emails associated with a given related entity (e.g. an invoice id)

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.

Example:sent_at

Field to sort by

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.

Example:desc

Sort order direction

Response

Email history retrieved successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "emails": [
      {
        "email_type": "INVOICE_EMITTED",
        "related_entity_type": "INVOICE"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.