Get the email configuration of a company
Scopecompanies:readReturns 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_idandsender.local_part: what the company chose. Alocal_partthat isnullmeansfacturas.sender.effective: the address the next invoice email will go out from, and why (reason). WithsourceBEELit 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_idis 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 isnullwhen it is not set.- Domain no longer verified: invoice emails go out from BeeL. without interruption, and
reasonreports it. - Environment: the configuration belongs to the company and is the same in test and live.
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
Unique identifier (UUID) of the company the operation acts on: its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/email-configuration"{
"success": true,
"data": {
"sender": {
"source": "ACCOUNT_DEFAULT",
"email_domain_id": null,
"local_part": null,
"effective": {
"from_address": "facturas@facturas.ejemplo.com",
"reason": "CUSTOM_DOMAIN",
"email_domain_id": "550e8400-e29b-41d4-a716-446655440000"
}
},
"defaults": {
"subject": "Invoice {invoiceNumber}",
"message": "Dear {customerName}, please find attached invoice {invoiceNumber}.",
"cc": [
"administracion@ejemplo.com"
],
"additional_recipients": null
}
}
}{
"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"
}
}Remove an email domain DELETE
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.
Replace the email configuration of a company PUT
Replaces the sender chosen for the invoice emails of the company, and optionally their defaults. It does not affect other emails. The sender is a replacement, not a merge: a property that is omitted or `null` goes back to its default, which is to inherit the default email domain of the account and to use `facturas` as the `local_part`. The response is the configuration as it is after the change, including the address in effect. - **`sender.source`:** when omitted it is `EMAIL_DOMAIN` if `email_domain_id` is sent and `ACCOUNT_DEFAULT` otherwise. `email_domain_id` is accepted only with `EMAIL_DOMAIN`, and `local_part` is not accepted with `BEEL`: any other combination answers `422` `VALIDATION_ERROR`. - **`defaults`:** omitted, the stored defaults stay as they are. `null` removes them. An object replaces all of them, so a property left out of it is removed. Sending an object requires the email customization plan: without it the call answers `403` `FEATURE_NOT_AVAILABLE`, and the sender is not changed. The templates accept the variables listed by `GET /v1/email-template-variables`. - **`email_domain_id`:** an email domain of the account that has already been registered. A domain that does not exist, belongs to another account or was removed answers `404` `EMAIL_DOMAIN_NOT_FOUND`; one that is still being registered answers `409` `EMAIL_DOMAIN_NOT_READY`. Choosing a domain that is not verified is allowed: until it is verified, invoice emails go out from the default email domain of the account if that one is verified, and from BeeL. otherwise. - **`local_part`:** up to 64 characters: lowercase letters, digits and the symbols `!#$%&'*+/=?^_\`{|}~-`, with single dots between groups. Any other value answers `422` `VALIDATION_ERROR`. - **Removed email domains:** when the email domain a company chose is removed, the company goes back to `ACCOUNT_DEFAULT` and keeps its `local_part`. - **Credentials:** it changes the address real invoices are sent from, so it requires a live API key and the `companies:write` scope. A test API key answers `403` `LIVE_CREDENTIAL_REQUIRED`. Send an `Idempotency-Key` so a retry does not repeat the operation. - **Environment:** the configuration belongs to the company and is the same in test and live.