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

# How it works

> One Minimo workspace for your app, one tenant per restaurant: what Minimo runs, what stays in your app, and what each restaurant gets

Minimo gives **your customers** email (booking confirmations, reminders, review requests, campaigns) without you
building an email platform. The example in these pages is a restaurant-manager app: each **restaurant** is one of
your customers, and each restaurant emails its **guests**. Words are defined in the [glossary](https://docs.minimo.it/embedded/glossary.md).

* **One workspace for your whole app.** You sign up once. Your restaurants never get a Minimo account.
* **One `tenant` per restaurant.** A string you choose, such as your restaurant id (`restaurant_4812`). Minimo keeps
  each restaurant's templates, guests, consent, sends and statistics apart. The same address at two restaurants is
  two guests.
* **Restaurants work inside your app.** Minimo widgets are ready-made screens you embed with one line of JavaScript,
  in English or Italian.
* **Your backend says what happened, Minimo sends.** Send the email now, or send booking events and let Minimo send
  each email at the right time, and cancel it when the booking is cancelled.

```mermaid theme={null}
flowchart TB
  be["Your backend<br/>(API key)"]
  fe["Your web app<br/>(restaurant area)"]
  api["Minimo API"]
  widgets["Minimo widgets"]
  engine["Minimo: rules and clock,<br/>consent, protections, sending"]
  guests["Each restaurant's guests"]
  be -- "sessions, events, sends" --> api
  fe -- "iframe + widgets.js" --> widgets
  widgets -. "events" .-> fe
  api --> engine
  widgets --> engine
  engine -- "email from the<br/>restaurant's domain" --> guests
```

## Who does what

| Minimo runs | Your SaaS keeps |
| - | - |
| The screens your restaurants use: automatic messages and the email editor, campaigns, contacts, send history, statistics, brand | Where the screens live in your app, who can open them, your navigation and your plans |
| The timing of every automatic email (now, 24 hours before, 2 hours after), retries, deduplication, cancellation when the booking is cancelled | Telling Minimo what happened: one event per booking change |
| Sending, the sender domain, DKIM and bounces, unsubscribe links and pages, consent records | Your booking data and your customer relationship |
| Protections: new restaurants start with a daily limit on marketing emails, bad lists are refused, a restaurant with complaints is paused alone | Your API key, on your server only |
| Per-restaurant numbers: what was sent, opened, clicked, bounced, for your charts and your invoices | Pricing to your restaurants |

## What a restaurant gets

| Widget | What the restaurant does |
| - | - |
| [Automatic messages](https://docs.minimo.it/embedded/widget-automatic-messages.md) | Sees the emails it sends automatically, previews them, personalizes texts, colors and logo in the Minimo editor, switches each one on or off |
| [Campaigns](https://docs.minimo.it/embedded/widget-campaigns.md) | Writes a promotion from a template you prepared and sends it to its own guests who agreed to receive it |
| [Contacts](https://docs.minimo.it/embedded/widget-contacts.md) | Manages its own guests: search, add one or paste a list with consent, fix, remove, download as CSV |
| [Send history](https://docs.minimo.it/embedded/widget-history.md) | Sees the latest emails sent to its guests and what happened to them |
| [Statistics](https://docs.minimo.it/embedded/widget-statistics.md) | Sees how its emails perform over 7, 30 or 90 days, with a plain sending status |
| [Brand](https://docs.minimo.it/embedded/widget-brand.md) | Sets its logo, color, contacts, social links and legal details once: every email follows |
| [WhatsApp](https://docs.minimo.it/embedded/widget-whatsapp.md) | **Coming soon.** Today automatic messages and campaigns are email only. |

Plus two things that need no widget: guests unsubscribe on pages that show the restaurant's name and logo ([consent](https://docs.minimo.it/embedded/consent.md)), and every restaurant can send from its own domain or from a subdomain of yours ([domain connect](https://docs.minimo.it/embedded/domain-connect.md), [senders](https://docs.minimo.it/embedded/senders-and-sending.md)).

## Guests and the contacts API

> [!WARNING]
>
> **Save your widget settings first.** Minimo keeps each restaurant's guests apart only once your widget settings exist. Call `PUT /public/v1/widgets/settings` with at least `allowedOrigins` (see [Embedded widgets](https://docs.minimo.it/embedded/widgets.md)). Do it before your first send, booking event or contact with `tenant`.
>
> Until then, `tenant` is only a label on the message. Each email address is one contact of your workspace, shared by all restaurants. Consent and protections per restaurant do not apply yet.

Your API key reaches every restaurant of your workspace. On the contacts API, `tenant` says which restaurant's guest you mean:

| Call | Without `tenant` | With `tenant` |
| - | - | - |
| `GET /public/v1/contacts/by-email/{email}` | The contact of your workspace | The guest of that tenant (unknown tenant: `404 TENANT_NOT_FOUND`) |
| `POST /public/v1/contacts` | Creates or updates a contact of your workspace | Creates or updates the guest of that tenant (the tenant is created on first use) |
| Sends, booking events, opt-out | Your workspace | That tenant's guest |
| `PUT` / `DELETE /public/v1/contacts/{id}`, contact history | The contact with that id, whatever its tenant | (not taken: the id already names one contact) |

An update by id keeps the guest in its tenant: it never starts your workspace automations and its consent changes only with evidence (use the [subscriptions API](https://docs.minimo.it/embedded/consent.md#subscriptions-api)).

## API keys and permissions

Every call from your backend uses one API key (`Authorization: Bearer mn-…`), kept on your server. You create it in
**Developer → API keys** ([Quickstart, step 1](https://docs.minimo.it/embedded/quickstart.md)). The embedded endpoints use these
permissions:

| Permission | For |
| - | - |
| **Widgets** | Widget settings and sessions, restaurant profiles, rules |
| **Events** | Booking events and the emails they schedule |
| **Widgets** or **Events** | Restaurant statistics, reputation, marketing hold, consent |
| **Transactional** | Sending an email now or at a time (`sendAt`), the message list |
| **Domains** | The domain popup and senders |

The key form starts with Subscribe, Transactional, Stats, Webhook and Goals selected. Keep Transactional. Remove the
others: the embedded pages do not need them. Open the list to add Widgets, Events and Domains.
A permission cannot be added to a key later: create a new key. A key without the permission an endpoint needs gets
`401 INVALID_TOKEN`, the same answer as a wrong key.

## Language and look

* The widgets, the editor and the domain popup are in **English** and **Italian** only (the `locale` you pass).
  There is no Spanish or German version. A `locale` other than `en` or `it` is refused with `400 INVALID_PARAMETERS`.
  Pass `en` or `it` for a restaurant that speaks another language.
* The unsubscribe pages are in English or Italian too. A guest whose language is neither sees English.
* The emails are in the language you write them in. Any language works.
* The widget pages show a small "Email by Minimo" line. Pass `poweredBy: false` and they carry no Minimo name.
* The emails your restaurants send **never** carry a Minimo badge.

## Next step

[Quickstart: send the first email for a restaurant](https://docs.minimo.it/embedded/quickstart.md)

Related: [Start here](https://docs.minimo.it/embedded/start-here.md) · [Go live](https://docs.minimo.it/embedded/go-live.md) ·
[Errors and limits](https://docs.minimo.it/embedded/errors.md)


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