NewRecurring invoices: `series_id` is optional
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Emails

List the email domains

Scopeemail-domains:read

Returns the domains the account sends its emails from, each with the DNS records to publish and the verification status of the domain and of every record. It only reads; it does not register or verify anything.

  • Without the add-on: the list is still returned, so you can see what the account holds, and max_email_domains is 0.
  • max_email_domains: the maximum number of domains the custom email domain add-on allows the account; null when the add-on sets no explicit limit. The add-on is contracted with BeeL.
  • verified_at and last_checked_at: absent until the domain is verified or checked for the first time.
  • Environment: domains belong to the account and are the same in test and live.

Closed catalogue. The domains of an account are a short, bounded set: the response carries no pagination, the operation takes no paging parameters, and every response holds the whole set.

GET
/v1/accounts/{account_id}/email-domains

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. The account in the path, 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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/email-domains"
{
  "success": true,
  "data": {
    "email_domains": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "domain": "facturas.ejemplo.com",
        "status": "PENDING",
        "is_default": true,
        "dns_records": [
          {
            "type": "MX",
            "name": "send",
            "value": "mail.example.com",
            "priority": 10,
            "status": "PENDING"
          },
          {
            "type": "TXT",
            "name": "send",
            "value": "v=spf1 include:example.com ~all",
            "status": "PENDING"
          }
        ],
        "created_at": "2025-01-20T14:30:00Z"
      }
    ],
    "max_email_domains": 3
  },
  "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": "The invoice must have at least one line",
  "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"
  }
}

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. **Closed catalogue.** This collection is fixed and bounded by the request itself — at most one indicator per id in `related_entity_ids`: it carries no `pagination`, it takes no `page`/`limit`, and every response holds the whole set.

Register an email domain POST

Registers a domain to send your account's emails from and returns the DNS records you have to publish for it. The domain starts `PENDING`; publish the records and ask for the check with `POST /v1/accounts/{account_id}/email-domains/{email_domain_id}/verify`. A domain that is not `VERIFIED` 72 hours after it was registered is removed and its name is freed. - **Add-on:** requires the custom email domain add-on, which is contracted with BeeL. Without it the call answers `403 FEATURE_NOT_AVAILABLE`. - **Default:** the first domain of an account, or the new one when the account has no default domain, becomes the default; otherwise the default does not change. - **`EMAIL_DOMAIN_INVALID` (`422`):** the text is not a full domain name. Internationalised names are accepted and stored in their ASCII form. - **`EMAIL_DOMAIN_RESERVED` (`422`):** the domain cannot be used as a sending domain, for example because it belongs to BeeL or to a public mailbox provider. - **`EMAIL_DOMAIN_UNAVAILABLE` (`409`):** the domain is already in use: registered by your account, by another account, or already held in the sending service BeeL uses. The answer is the same in every case and says nothing about who holds it. - **While it registers:** a domain that is still registering shows `status: PENDING` with `dns_records: []`. Read it again in a few seconds; if it stays that way, remove it with `DELETE` and register it again. - **`EMAIL_DOMAIN_LIMIT_REACHED` (`409`):** the account already holds as many domains as the add-on allows; `error.details.limit` carries that number. - **Unpaid billing:** when the billing of the account is unpaid the call answers `402 PAYMENT_REQUIRED`. - **Credentials:** it changes the real account, so it requires a live API key or a dashboard session. A test API key answers `403 LIVE_CREDENTIAL_REQUIRED`. Send an `Idempotency-Key` so a retry does not repeat the operation.