Skip to main content
Each restaurant sends from its own domain, or from a subdomain of yours. Once a domain is verified (with the domain popup or POST /public/v1/domains), three things are left:
  1. Senders: the addresses a domain sends as (bookings@…, noreply@…).
  2. The sender of each send: which address an email goes out from.
  3. tenant: which restaurant a send belongs to, for its history, its statistics and your billing.

Example: send from the restaurant’s domain

The email goes out from sender 34 (an address on the restaurant’s domain), counts for restaurant_4812, and replies go to the restaurant’s own mailbox. Each part is explained below.

Before you start

  • An API key with the Domains permission (domains) for senders, and the Transactional permission (transactional) for sending. One key can have both. Keep it on your server.
  • At least one verified domain in your workspace (status: "verified" in GET /public/v1/domains).

1. Manage senders

All routes are scoped to one domain ({id} from GET /public/v1/domains). An address must live under that exact domain, and the domain must be verified.
422 when the address is not under that domain (SENDER_NOT_ON_DOMAIN) or the domain is not verified yet (SENDER_DOMAIN_NOT_VERIFIED). A domain of another workspace is 404. To move a sender to another domain, delete it and create it under the other one.
A verified domain already has a default sender, created at verification: info@ for a transactional domain, hello@ for a marketing one.

2. Choose the sender on each send

These endpoints accept the sender per call:
  • POST /public/v1/emails (one-shot HTML)
  • POST /public/v1/transactionals and POST /public/v1/templates/email/send (templates)
  • POST /public/v1/campaigns/{id}/send
Use one of: Never a silent fallback. If the sender is not under a verified domain of your workspace, the send is refused with 422 and nothing goes out. The codes (SENDER_NOT_ALLOWED, SENDER_NOT_FOUND, SENDER_DOMAIN_NOT_VERIFIED, SENDER_PARAM_CONFLICT, INVALID_SENDER_ADDRESS, INVALID_REPLY_TO) are in Errors and limits. Without any of these fields, nothing changes: the template’s sender or the workspace default is used, exactly as before.
For a marketing campaign, a workspace with a verified marketing domain (for example news.<domain>) sends from it, for reputation isolation.

Customers without a domain: a subdomain of yours

Verify your own domain once (for example yoursaas.example). Then from / fromAddress can use any subdomain of it with no DNS of its own, one per customer:
The email is signed by your verified domain, so it passes the mailbox checks without any DNS record for trattoriadamario.yoursaas.example. A subdomain that is registered as a domain of its own (in any workspace, verified or not) is refused with SENDER_NOT_ALLOWED: connect and verify it like any domain instead.

Replies to your customer’s mailbox

Add replyTo to POST /public/v1/transactionals or POST /public/v1/templates/email/send to choose where replies go, for example your customer’s own mailbox. Any mailbox, "Name <address>" or a bare address:
Without it, the Reply-To is your workspace’s inbox address when it is set as reply-to, otherwise none. A malformed value is refused with 422 INVALID_REPLY_TO. Booking events take the same replyTo (see Booking events).
A restaurant that only has a Gmail (or any other public mailbox) cannot send as that address: from must be under a domain verified in your workspace, and gmail.com cannot be verified, so it answers 422 SENDER_NOT_ALLOWED. Send from a subdomain of yours, such as bookings@trattoriadamario.yoursaas.example with the restaurant’s name, and put its Gmail in replyTo.

3. Name the customer with tenant

Add tenant to POST /public/v1/emails, /public/v1/transactionals or /public/v1/templates/email/send: your own reference for the customer, up to 64 characters among letters, digits, ., _, : and -, starting with a letter or digit. It is stored on the message, and once your widget settings are saved the recipient becomes that customer’s guest. Read it back:
The response is a list inside data.data:
Reference: List Sent Messages. Each item carries tenant. Its id is the email provider’s message id. It is not the id that POST /public/v1/emails returned. To follow one send, keep the returned id and call GET /public/v1/emails/{id}/stats (it returns tenant too). Count the items per tenant to meter and rebill your customers.

Putting it together

  1. The restaurant connects trattoriadamario.example in the popup: your page gets domain.verified.
  2. Your backend adds prenotazioni@trattoriadamario.example and keeps the returned id with the restaurant.
  3. Every email for that restaurant is sent with senderId and tenant.
  4. At month end, GET /public/v1/messages/list?tenant=… per restaurant.

Next step

Embedded domain connect: let restaurants verify their domain inside your app.