POST /public/v1/domains), three things are left:
- Senders: the addresses a domain sends as (
bookings@…,noreply@…). - The sender of each send: which address an email goes out from.
tenant: which restaurant a send belongs to, for its history, its statistics and your billing.
Example: send from the restaurant’s domain
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"inGET /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/transactionalsandPOST /public/v1/templates/email/send(templates)POST /public/v1/campaigns/{id}/send
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.
Customers without a domain: a subdomain of yours
Verify your own domain once (for exampleyoursaas.example). Then from / fromAddress can use any subdomain of it with no DNS of its own, one per customer:
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
AddreplyTo 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:
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:
data.data:
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
- The restaurant connects
trattoriadamario.examplein the popup: your page getsdomain.verified. - Your backend adds
prenotazioni@trattoriadamario.exampleand keeps the returnedidwith the restaurant. - Every email for that restaurant is sent with
senderIdandtenant. - At month end,
GET /public/v1/messages/list?tenant=…per restaurant.