Custom sending domain

By default, invoice emails go out from a BeeL. address with the company's trade name as the sender name. With a custom sending domain they go out from an address on a domain you own, such as facturas@mail.example.com. Each company can use the account's default domain, pick another one, or stay on BeeL.'s address.

The domain belongs to the account, not to a company, and it is the same in Test and Live.

Domain paths hang off /v1/accounts/{account_id}. Reading needs the email-domains:read scope and writing needs email-domains:write.

Before you start

• The add-on. Custom sending domains are an Enterprise add-on, not part of the self-service plans: talk to sales to add it. Without it, registering or verifying a domain answers 403 FEATURE_NOT_AVAILABLE, and the list shows max_email_domains: 0. Reading, deleting and choosing the default still work.
• A live API key for writes. Domains are not scoped to an environment, so registering, verifying, deleting or changing the default with a test key answers 403 LIVE_CREDENTIAL_REQUIRED. Reads work with either key.
• Access to the domain's DNS, to publish the records BeeL. gives you.

Which address an email actually uses

GET …/email-configuration returns sender.effective, the address the next invoice email of that company will use, and a reason:

The candidates are the company's chosen domain first and then the account's default; the first one that is VERIFIED is used. If none is, the email goes out from BeeL.'s address. Sending never stops because of a domain: a domain that is pending, fails its check or is removed only changes the address, and reason tells you why.

If a domain is rejected at the moment of sending, the same email is sent again from BeeL.'s address and the domain is marked FAILED, which sends email_domain.failed.

The sender name and the reply-to address do not change: the sender name is the company's trade name and replies go to the company's email.

Default subject, message and recipients

The same PUT …/email-configuration takes defaults for the company's invoice emails: subject, message, cc and additional_recipients (always added to every invoice email). Leave defaults out to keep them, send null to clear them, or send an object to replace all of them. Setting them needs the email customization feature of your plan; without it the call answers 403 FEATURE_NOT_AVAILABLE and the sender is not changed either.

Subject and message accept placeholders written in braces, such as {invoiceNumber} or {customerName}, which are filled in when the email is sent. GET /v1/email-template-variables lists them. A placeholder that is not in the list is sent as written.

Webhooks

Each event fires once per change, only to the Live endpoints of the account that owns the domain. They carry no company_id, because a domain belongs to the account.

Gotchas

• Deleting a domain in use is allowed. Companies that had chosen it go back to ACCOUNT_DEFAULT and keep their local_part. If it was the default, the account is left without one, and email goes out from BeeL.'s address until you set another.
• A default can be pending. You can make a PENDING or FAILED domain the default; email only leaves from it once it is VERIFIED.
• The name may stay taken for a while. A deleted domain is usually free at once, but registering it again can occasionally answer EMAIL_DOMAIN_UNAVAILABLE for a while. If it persists, contact support.
• Saved templates use English placeholders. Templates saved with the older Spanish placeholders ({numeroFactura} and the like) have been rewritten with their English names, so reading them back shows {invoiceNumber}. The Spanish names are still filled in if you send them.

Related