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

# Quickstart

> Send the first email for a restaurant and show it inside your app, in 5 steps with copy-paste samples

At the end of this page your backend has sent an email for a test restaurant, and your app shows that restaurant its
send history in a Minimo widget. You need a backend that can make HTTPS calls and a web page you control. No template
is needed to start.

Replace `YOUR_MINIMO_KEY` with your key, and use a test inbox you own as the guest address.

**1. Create an API key**

In [app.minimo.it](https://app.minimo.it/developer/api-keys) open **Developer → API keys** and press **Create new
API key**. The dialog starts with **Subscribe**, **Transactional**, **Stats**, **Webhook** and **Goals**
already selected. Keep **Transactional** and remove the others. Then open the list and add **Widgets** and
**Events**. Add **Domains** only if your backend will add domains or senders through the API. You can also
verify your domain in the dashboard. Copy the key (`mn-…`): it is shown once. Keep it on your server.

> [!NOTE]
>
> Until the first credit top-up in **Settings → Plan & billing**, your workspace sends at most **100 emails a
> day** (UTC). That is enough for this page and for tests.

**2. Turn on restaurants (do this first)**

Save your widget settings. `allowedOrigins` are the web pages of your app that will show Minimo widgets.

```bash theme={null}
curl -X PUT https://api.minimo.it/public/v1/widgets/settings \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowedOrigins": ["https://app.yoursaas.example", "http://localhost:3000"] }'
```

```json theme={null}
{
  "data": {
    "allowedOrigins": ["https://app.yoursaas.example", "http://localhost:3000"],
    "masterTemplateIds": [],
    "masterTemplateUids": []
  }
}
```

From now on, each `tenant` you send is a separate restaurant with its own guests, consent and statistics. Before
this call, `tenant` is only a label and all restaurants share the same guests. No page with widgets yet? Put only
`http://localhost:3000` and add your real origins later.

Later, when you have master templates, call it again with `masterTemplateIds` (their uids). Each field you send
replaces only that list.

**3. Send the first email**

Name the restaurant with `tenant`: a string you choose, for example your restaurant id. The restaurant is created
on first use.

> [tab] Your HTML
>
> Your app writes the email; Minimo delivers it.
>
> ```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>Hi Anna, see you on Friday at 20:30.</p>",
>     "tenant": "restaurant_4812"
>   }'
> ```
>
> ```json theme={null}
> {
>   "data": {
>     "id": "7OA38FO",
>     "status": "sent",
>     "messageId": "<0107…@eu-central-1.amazonses.com>",
>     "statsUrl": "/public/v1/emails/7OA38FO/stats"
>   }
> }
> ```
>
> `GET /public/v1/emails/7OA38FO/stats` tells you later if it was opened or clicked.

> [tab] A Minimo template
>
> You create the template once. There are two ways:
>
> * In the Minimo dashboard: **Templates → Create new template → Create email template**. Give it a subject.
> * With your API key: [`POST /public/v1/ai/transactional-templates`](https://docs.minimo.it/api-reference/messaging-channels/email/create-template).
>   You describe the email and Minimo writes it. It always has a subject.
>
> Each restaurant can personalize its own copy. Name the template by its **uid**, the short code in the UID
> column (here `TRF4MS9`). The API returns it as `uid`.
>
> ```bash theme={null}
> curl -X POST https://api.minimo.it/public/v1/transactionals \
>   -H "Authorization: Bearer YOUR_MINIMO_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "transactional": "TRF4MS9",
>     "recipient": "guest@example.com",
>     "tenant": "restaurant_4812",
>     "customFields": { "GUEST_NAME": "Anna", "BOOKING_TIME": "20:30" }
>   }'
> ```
>
> ```json theme={null}
> { "data": { "status": 200, "sent": 1 } }
> ```
>
> `customFields` fill the merge fields of the template, written `{GUEST_NAME}` in the template.

Until you verify a domain of yours, the email goes out from a shared Minimo address with your workspace's name.
That is fine for tests. For real restaurants you send from your own domain: see
[Senders and domains](https://docs.minimo.it/embedded/senders-and-sending.md).

**4. Create a widget session (your backend)**

When a restaurant opens the page, your backend asks Minimo for a session for that restaurant and gives only the
URLs to the browser.

```js server/minimo-widgets.js theme={null}
export async function createWidgetSession(restaurant) {
  const res = await fetch('https://api.minimo.it/public/v1/widgets/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MINIMO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      tenant: restaurant.id, // the same string you send as tenant
      tenantName: restaurant.name, // shown in the widgets and the emails
      locale: 'en', // only 'en' or 'it'
    }),
  });
  if (!res.ok) throw new Error(`Minimo session failed: ${res.status}`);
  const { data } = await res.json();
  return data.urls; // { templates, campaigns, history, contacts, brand, whatsapp, stats }
}
```

Expose it to your page behind your own login, for example `GET /api/minimo/widgets`. A session lasts 60 minutes:
create a new one each time the page opens, and never share it between restaurants.

**5. Show the widget in your page**

```html theme={null}
<div id="minimo-history"></div>
<script src="https://api.minimo.it/public/v1/embed/widgets/widgets.js"></script>
<script>
  fetch('/api/minimo/widgets')
    .then((r) => r.json())
    .then((urls) => {
      Minimo.mountWidget({
        url: urls.history,
        container: '#minimo-history',
        minHeight: 600,
        onEvent: (event) => console.log(event.widget, event.type),
      });
    });
</script>
```

The restaurant sees the email you sent in step 3. Mount `urls.stats` the same way for its statistics, and
`urls.templates` for its automatic messages once you have [master templates](https://docs.minimo.it/embedded/glossary.md).

## If a call fails

Every error body is `{ "status": "FAIL", "message": "<CODE>", "userMessage": "…" }`. Read `userMessage` first: it
says what to fix. The most common ones:

* `401 INVALID_TOKEN`: wrong key, or the key lacks the permission of that endpoint.
* `400 INVALID_PARAMETERS`: a field is wrong, or the widget settings of step 2 are missing.
* `402 QUOTA_EXCEEDED`: the 100 emails a day before the first top-up.

All codes: [Errors and limits](https://docs.minimo.it/embedded/errors.md).

## Next step

[Go live: the checklist before your first real restaurant](https://docs.minimo.it/embedded/go-live.md)

Related: [Rules](https://docs.minimo.it/embedded/automations.md) (let Minimo time the reminders) ·
[All widgets](https://docs.minimo.it/embedded/widgets.md) · [How it works](https://docs.minimo.it/embedded/overview.md)


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