NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Emails

List the email history

Scopeemails:read

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.

GET
/v1/emails

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Query Parameters

page?integer

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

Default1
Range1 <= value
limit?integer

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

Default20
Range1 <= value <= 100
type?string

Filter by email type (e.g. INVOICE_EMITTED)

status?string

Filter by delivery status

Value in"QUEUED" | "REJECTED" | "SENT" | "FAILED" | "DELIVERED" | "BOUNCED" | "OPENED"
recipient?string

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

related_entity_id?string

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

Formatuuid
sort_by?string
Value in"sent_at" | "status" | "email_type"
sort_order?string
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/emails"
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email_type": "INVOICE_EMITTED",
        "recipients": [
          "cliente@ejemplo.com"
        ],
        "cc": [],
        "subject": "Factura 2025/0001",
        "related_entity_type": "INVOICE",
        "related_entity_id": "660e8400-e29b-41d4-a716-446655440111",
        "status": "SENT",
        "sent_at": "2025-01-20T14:30:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "items_per_page": 20,
      "total_items": 1,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  },
  "meta": {
    "timestamp": "2025-01-20T15:00:00Z",
    "request_id": "req_123"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation constraint violation.",
    "details": {
      "limit": "must be greater than or equal to 1"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Get the email indicators of several entities GET

Returns, for each related entity id given, how many emails the history holds for it, the status of the most recent one and when it was sent. Lets you show the state of an entity's email without loading its full history. - **`last_status`:** carries whatever the latest attempt ended in, `REJECTED` and `QUEUED` included, so a `count` above zero does not mean an email reached anyone. - **Ids with no associated emails:** omitted from the response rather than returned with `count` 0.

Get an email of the history GET

Returns one recorded email with its message body (HTML and plain text), its attachments and, for batch emails, the invoices it carried. - **`body_available`:** the body is fetched live and is only available while the message has a provider message id and the provider still retains it; otherwise it is `false` and `html_body` / `text_body` are `null`. - **An email that never left:** `QUEUED` or `REJECTED`, it has no body for that reason. - **Deprecated:** use `GET /v1/accounts/{account_id}/emails/{email_id}`, which behaves identically.