> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimo.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Senders and domains

> Manage each customer domain senders via API, send every email from the right domain, and tag it with your tenant for stats and rebilling

Each restaurant sends from **its own domain**, or from a subdomain of yours. Once a domain is verified (with the
[domain popup](https://docs.minimo.it/embedded/domain-connect.md) 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

```bash theme={null}
curl -X POST https://api.minimo.it/public/v1/emails \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "guest@example.com",
    "subject": "Your table is confirmed",
    "html": "<p>See you on Friday at 20:30.</p>",
    "senderId": 34,
    "tenant": "restaurant_4812",
    "replyTo": "owner@trattoriadamario.example"
  }'
```

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.

```bash theme={null}
# List the senders of domain 812
curl https://api.minimo.it/public/v1/domains/812/senders \
  -H "Authorization: Bearer YOUR_MINIMO_KEY"

# Add one
curl -X POST https://api.minimo.it/public/v1/domains/812/senders \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "prenotazioni@trattoriadamario.example", "displayName": "Trattoria Da Mario"}'
```

```json theme={null}
{
  "data": {
    "id": 34,
    "email": "prenotazioni@trattoriadamario.example",
    "displayName": "Trattoria Da Mario",
    "domainId": 812,
    "domain": "trattoriadamario.example",
    "verified": true
  }
}
```

| Route | What it does |
| - | - |
| [`GET /public/v1/domains/{id}/senders`](https://docs.minimo.it/api-reference/domains/list-senders) | Lists the domain's senders with their stable `id`. |
| [`POST /public/v1/domains/{id}/senders`](https://docs.minimo.it/api-reference/domains/add-sender) | Adds `{ email, displayName? }`. `409` if the address already exists. |
| [`PATCH /public/v1/domains/{id}/senders/{senderId}`](https://docs.minimo.it/api-reference/domains/update-sender) | Changes `email` (same domain) and/or `displayName`. |
| [`DELETE /public/v1/domains/{id}/senders/{senderId}`](https://docs.minimo.it/api-reference/domains/delete-sender) | Removes the sender. `204`, or `404` if it does not exist. |

`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.

> [!NOTE]
>
> 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:

| Field | Example | Notes |
| - | - | - |
| `senderId` | `34` | A sender from step 1. Its display name is used unless you pass `fromName`. |
| `from` | `"Trattoria Da Mario <prenotazioni@trattoriadamario.example>"` | Address with an optional name. Any address under a verified domain of your workspace. |
| `fromAddress` | `"prenotazioni@trattoriadamario.example"` | Same rule as `from`, address only (with `fromName` for the name). |

**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](https://docs.minimo.it/embedded/errors.md#sending).

Without any of these fields, nothing changes: the template's sender or the workspace default is used, exactly as before.

> [!TIP]
>
> 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:

```json theme={null}
{ "from": "Trattoria Da Mario <bookings@trattoriadamario.yoursaas.example>" }
```

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:

```json theme={null}
{ "from": "Trattoria Da Mario <bookings@trattoriadamario.yoursaas.example>",
  "replyTo": "Trattoria Da Mario <owner@trattoriadamario.example>" }
```

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](https://docs.minimo.it/embedded/events.md#send-events-your-backend)).

> [!NOTE]
>
> 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](https://docs.minimo.it/embedded/quickstart.md) are saved the recipient becomes that customer's guest.

Read it back:

```bash theme={null}
# Every message of one tenant (newest first)
curl "https://api.minimo.it/public/v1/messages/list?tenant=restaurant_4812" \
  -H "Authorization: Bearer YOUR_MINIMO_KEY"
```

The response is a list inside `data.data`:

```json theme={null}
{ "data": { "data": [
  { "id": "<0107…@eu-central-1.amazonses.com>", "subject": "Your table is confirmed",
    "timestamp": "2026-11-13T09:41:00.000Z", "seenTimestamp": null, "senderEmail": "", "tenant": "restaurant_4812" }
] } }
```

Reference: [List Sent Messages](https://docs.minimo.it/api-reference/embedded/tenants/list-messages.md). 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](https://docs.minimo.it/embedded/domain-connect.md): let restaurants verify their domain inside your app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.