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

Get an email domain

Scopeemail-domains:read

Returns one domain of your account with the DNS records to publish and the verification status of the domain and of every record. It only reads; it does not verify anything. A domain still registering shows status: PENDING with dns_records: [].

It works without the custom email domain add-on, so you can inspect what the account holds. A domain of another account, or one already removed, answers 404.

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

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
email_domain_idstring

Identifier of the email domain.

Formatuuid

Response Body

application/json

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/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "success": true,
  "data": {
    "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"
      }
    ],
    "created_at": "2025-01-20T14:30:00Z"
  },
  "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": "EMAIL_DOMAIN_NOT_FOUND",
    "message": "No email domain with that id belongs to your account."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}

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.

Verify an email domain POST

Asks for the DNS records of the domain to be checked, once you have published them. The check is asynchronous: the call returns `202` with the domain as it is now, usually still `PENDING`, and its `status` changes to `VERIFIED` or `FAILED` when the check finishes. Read the domain with `GET` to see the result. 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`. - **`EMAIL_DOMAIN_NOT_READY` (`409`):** the domain is still registering (`dns_records: []`); repeat the call in a few seconds. - **Sending service failure:** if the check cannot be requested the call fails with `502` and nothing changes. - **Unpaid billing:** when the billing of the account is unpaid the call answers `402 PAYMENT_REQUIRED`. - **Credentials:** 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.