# Get the email configuration of a company API Reference 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. ## GET /v1/companies/{company_id}/email-configuration **Get the email configuration of a company** 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. ### Authentication Accepts any of: - `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`) ### Parameters - **company_id** (required) in path `string`: 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. ### Responses #### 200: Email configuration of the company **Content `application/json`:** - **success** (required) `boolean`: No description (example: true) - **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - **meta** `ResponseMeta` - **data** (required) `CompanyEmailConfiguration` **Example:** ```json { "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 } } } ``` #### 401: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Authentication is required to access this resource" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 403: Your account does not own or manage this company (`error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`), or the credential lacks the `companies:read` scope (`INSUFFICIENT_SCOPE`). **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") #### 429: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known. **Headers:** - `Retry-After` `integer`: Seconds until the rate limit resets - `RateLimit-Limit` `integer`: Maximum requests allowed in the window - `RateLimit-Remaining` `integer`: Remaining requests in the current window - `RateLimit-Reset` `integer`: Seconds until the current window resets **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "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" } } ``` #### 500: Internal server error **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### default: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "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" } } ``` --- # Related Schema Definitions ## SuccessResponse The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it. - **success** (required) `boolean`: No description (example: true) - **data** (required): The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - **meta** `ResponseMeta` ## ResponseMeta - **timestamp** `string` (date-time): No description (example: "2025-01-15T10:30:00Z") - **request_id** `string`: No description (example: "4bf92f3577b34da6a3ce929d0e0e4736") ## CompanyEmailConfiguration - **sender** (required) `CompanyEmailSender`: The sender chosen for the invoice emails of a company, and the one in effect. - **defaults** (required) `CompanyEmailDefaults`: The content applied to an invoice email that does not specify its own. The additional recipients are always added. ## ErrorResponse Error response shared by all BeeL. APIs. The payload carries **two contracts at once** (additive, non-breaking): - **Legacy** (`success`, `error.{code,message,details}`, `meta`) — kept intact for existing consumers. - **RFC 9457** (`type`, `title`, `detail`, `instance`) — new fields for integrators following Problem Details for HTTP APIs. The `type` URI is the stable, shareable link to the error's documentation page (e.g. `https://docs.beel.es/errors/{code}`). Future migration: the legacy fields will be deprecated via `Deprecation`/`Sunset` headers after a sufficient adoption window, and the response Content-Type will move to `application/problem+json`. - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") ## ErrorDetail - **code** (required) `string`: No description (example: "VALIDATION_ERROR") - **message** (required) `string`: No description (example: "The provided data is not valid") - **details** `object`: No description (example: {"field":"specific error message"}) ## CompanyEmailSender The sender chosen for the invoice emails of a company, and the one in effect. - **source** (required) `CompanyEmailSenderSource`: What the company chose as the sender of its invoice emails. - ACCOUNT_DEFAULT: no choice; it inherits the default email domain of the account. - EMAIL_DOMAIN: one of the email domains of the account, in `email_domain_id`. - BEEL: the address of BeeL. - **email_domain_id** (required) `string` (uuid): The email domain of the account the company chose; `null` unless `source` is `EMAIL_DOMAIN`. - **local_part** (required) `string`: Part of the address before the `@`. `null` means `facturas`, and it is always `null` when `source` is `BEEL`. (example: "cobros") - **effective** (required) `EffectiveEmailSender`: The address the invoice emails of a company go out from, and why. ## CompanyEmailDefaults The content applied to an invoice email that does not specify its own. The additional recipients are always added. - **subject** (required) `string`: Subject template, with the variables of `GET /v1/email-template-variables`. (example: "Invoice {invoiceNumber}") - **message** (required) `string`: Message template, with the variables of `GET /v1/email-template-variables`. (example: "Dear {customerName}, please find attached invoice {invoiceNumber}.") - **cc** (required) `array[Email]`: CC recipients, applied when the email request does not specify `cc`. - **additional_recipients** (required) `array[Email]`: Recipients added to those of every invoice email. ## CompanyEmailSenderSource What the company chose as the sender of its invoice emails. - ACCOUNT_DEFAULT: no choice; it inherits the default email domain of the account. - EMAIL_DOMAIN: one of the email domains of the account, in `email_domain_id`. - BEEL: the address of BeeL. Type: `string` — one of: ACCOUNT_DEFAULT, EMAIL_DOMAIN, BEEL ## EffectiveEmailSender The address the invoice emails of a company go out from, and why. - **from_address** (required) `string` (email): Address shown as the sender of the invoice emails. (example: "facturas@facturas.ejemplo.com") - **reason** (required) `EmailSenderReason`: Why invoice emails go out from the address they go out from. - CUSTOM_DOMAIN: from a verified email domain of the account. Nothing to do. - ADDON_INACTIVE: the company or the account has an email domain but the account does not hold the custom email domain add-on, so emails go out from BeeL. Contract the add-on with BeeL. to use the domain. - DOMAIN_NOT_VERIFIED: the email domains that apply are not verified, so emails go out from BeeL. Verify the domain with `POST /v1/accounts/{account_id}/email-domains/{email_domain_id}/verify` once its DNS records are published. - NO_DOMAIN: neither the company nor the account has an email domain, so emails go out from BeeL. Register one with `POST /v1/accounts/{account_id}/email-domains`. - BEEL_SELECTED: the company chose the address of BeeL. (`source` `BEEL`). Nothing to do. - **email_domain_id** `string` (uuid): The email domain of the account the address belongs to. Absent when the address is BeeL.'s. (example: "550e8400-e29b-41d4-a716-446655440000") ## Email Email address (minimum valid email is 5 chars, e.g. a@b.co) Type: `string` (email) ## EmailSenderReason Why invoice emails go out from the address they go out from. - CUSTOM_DOMAIN: from a verified email domain of the account. Nothing to do. - ADDON_INACTIVE: the company or the account has an email domain but the account does not hold the custom email domain add-on, so emails go out from BeeL. Contract the add-on with BeeL. to use the domain. - DOMAIN_NOT_VERIFIED: the email domains that apply are not verified, so emails go out from BeeL. Verify the domain with `POST /v1/accounts/{account_id}/email-domains/{email_domain_id}/verify` once its DNS records are published. - NO_DOMAIN: neither the company nor the account has an email domain, so emails go out from BeeL. Register one with `POST /v1/accounts/{account_id}/email-domains`. - BEEL_SELECTED: the company chose the address of BeeL. (`source` `BEEL`). Nothing to do. Type: `string` — one of: CUSTOM_DOMAIN, ADDON_INACTIVE, DOMAIN_NOT_VERIFIED, NO_DOMAIN, BEEL_SELECTED --- Full OpenAPI spec: https://docs.beel.es/api/openapi