List the email history

Returns the emails the system recorded on behalf of the account in the path: invoice deliveries, verification, onboarding. It only reads the history; it does not send or resend anything.

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.
Scope: the account is the one named in the path; the environment is not, and comes from the credential.

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

Path Parameters

account_idstring

Your own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a 403 is returned when you do not reach it, the same response an account that does not exist gets.

Formatuuid

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

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

curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/emails"

curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/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": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "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": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "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"
  }
}

List the email history

Authorization

Path Parameters

Query Parameters

Response Body

200application/json

400application/json

401application/json

403application/json

429application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json