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

Remove an email domain

Scopeemail-domains:write

Removes the domain from your account and from the email sending service, which frees the name so it can be registered again. The account's emails stop being sent from it.

  • Without the add-on: it works, so you can clean up what the account still holds.
  • Default domain: removing the default leaves the account without one; its emails go out from BeeL until you set another.
  • Name: the name is free for a new registration as soon as the call returns. If the removal in the sending service fails afterwards, an immediate new registration of the same name may answer EMAIL_DOMAIN_UNAVAILABLE for a while.
  • Still registering: a domain that stays PENDING with dns_records: [] is removed this way.
  • 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.
DELETE
/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

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/email-domains/497f6eca-6276-4993-bfeb-53cbbbba6f08"
Empty
{
  "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"
  }
}

Set the default email domain PUT

Makes this domain the one the account's emails are sent from by default, and clears the flag on the domain that had it, so the account always has at most one default. - **Repeatable:** it states the desired default rather than performing a change, so repeating the call on the domain that already is the default returns the same `200`. - **Any status:** a domain can be the default while it is still `PENDING` or `FAILED`. Emails only leave from it once it is `VERIFIED`; until then they go out from BeeL. - **Without the add-on:** it works, so an account can still choose among the domains it holds. - **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.

Get the email configuration of a company GET

Returns the address the invoice emails of the company are sent from and the defaults that apply when an invoice is sent by email. It applies only to invoice emails. - **`sender.source`, `sender.email_domain_id` and `sender.local_part`:** what the company chose. A `local_part` that is `null` means `facturas`. - **`sender.effective`:** the address the next invoice email will go out from, and why (`reason`). With `source` `BEEL` it is the address of BeeL. Otherwise it is resolved in this order: the email domain chosen by the company and the default email domain of the account, then the address of BeeL. Only email domains that are verified, and only while the account holds the custom email domain add-on, count. The add-on is contracted with BeeL. `email_domain_id` is present only when the address uses one of the account's email domains. - **`defaults`:** the content applied to an invoice email that does not specify its own. Each property is `null` when it is not set. - **Domain no longer verified:** invoice emails go out from BeeL. without interruption, and `reason` reports it. - **Environment:** the configuration belongs to the company and is the same in test and live.