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

# Rules: which email, and when

> Define once which email goes out for which booking event: confirmation now, reminder 2 hours before, review request after

Your backend does not need a scheduler. It tells Minimo what happened (an **event**, such as `booking.created`).
Minimo keeps the **rules** (which email, when) and the **clock**:

* a rule sends an email **right away**, or at an **offset** from a date in the event ("2 hours before `booking_at`");
* a `booking.cancelled` with the same `cancellationKey` cancels what is still pending; a `booking.updated` moves it;
* each restaurant can switch a rule off in the [automatic messages widget](https://docs.minimo.it/embedded/widget-automatic-messages.md);
* the email is the restaurant's own copy of the template when it personalized one.

No cron, no queue, no deduplication on your side. This page sets the rules. [Booking events](https://docs.minimo.it/embedded/events.md) sends
the events.

## Before you start

* An API key with the **Events** permission (`events`) to send events, and **Widgets** (`widgets`) to manage the rules. Keep it on your server.
* The email templates (masters) your tenants use, e.g. confirmation, reminder, review request. Create them in the
  Minimo dashboard (**Templates → Create new template → Create email template**) or with your API key
  ([`POST /public/v1/ai/transactional-templates`](https://docs.minimo.it/api-reference/messaging-channels/email/create-template), permission
  **Transactional**). Put the template's `uid` in `masterTemplateIds` and in your rules.
* Every template needs a subject. In the dashboard you type it. The API always saves one. A template without a subject
  is never sent: the send is recorded as `failed` with the reason `empty_subject`. Add a subject in the editor and the
  next sends go out.

## Define the rules once (for every restaurant)

```bash theme={null}
curl -X PUT https://api.minimo.it/public/v1/automation-rules \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      { "key": "confirmation", "name": "Booking confirmation", "event": "booking.created", "template": "TRF4MS9" },
      { "key": "reminder", "name": "Reminder 2 hours before", "event": "booking.created", "template": "76S8FOV",
        "offset": "-PT2H", "dateField": "booking_at" },
      { "key": "review", "name": "Review request", "event": "booking.created", "template": "4ZGJ92I",
        "offset": "PT2H", "dateField": "booking_at" },
      { "key": "cancellation", "name": "Booking cancelled", "event": "booking.cancelled", "template": "W4ZKXIP" }
    ]
  }'
```

The fourth rule sends the cancellation email: a `booking.cancelled` first cancels what is still pending for the booking (reminder, review request), then sends the emails of the rules it triggers.

| Field | Notes |
| - | - |
| `key` | Stable name of the rule. A tenant override uses the same key. |
| `event` | The event that schedules the send (compared ignoring case). |
| `template` | Template id or uid. Use the **master**: a tenant that personalized it gets its own copy at send time. |
| `offset` | Signed ISO 8601 duration from `dateField`: `-PT2H` 2 hours before, `PT2H` 2 hours after, `-P1D` a day before. Omitted: immediately. |
| `dateField` | Path of the date in the event payload (`booking_at`, `booking.date`). |
| `enabled` | Default `true`. |
| `cancelOn` | Events that cancel the pending sends with the same `cancellationKey`. Default: `<prefix>.cancelled` and `<prefix>.canceled` (`booking.created` → `booking.cancelled`). |
| `rescheduleOn` | Events that move a pending timed send to the new date. Default: `<prefix>.updated`. |

`PUT` adds or updates the rules you send (by key) and returns every rule with a readable `timing` ("Immediately", "2 hours before") and the template's `templateUid`; `GET /public/v1/automation-rules` lists them, `DELETE /public/v1/automation-rules/{key}` removes one (`204`). A rule with an `offset` and no `dateField` is refused (`422 INVALID_AUTOMATION_RULE`).

### Guests who speak different languages

A rule cannot choose the template by the guest's language. So use one master and one event name per language.
This is about the guests' emails. The widgets your restaurants use stay in English or Italian.
Set `cancelOn` and `rescheduleOn` yourself. The defaults come from the event name: with `booking.created.de` the
rule would wait for `booking.created.cancelled`.

```json theme={null}
{
  "rules": [
    { "key": "confirmation_de", "name": "Booking confirmation (de)", "event": "booking.created.de",
      "template": "DE4CNF1" },
    { "key": "reminder_de", "name": "Reminder 2 hours before (de)", "event": "booking.created.de",
      "template": "DE4RMD2", "offset": "-PT2H", "dateField": "booking_at",
      "cancelOn": ["booking.cancelled"], "rescheduleOn": ["booking.updated.de"] }
  ]
}
```

Your backend sends `booking.created.<language>` and `booking.updated.<language>` with the guest's language. One
`booking.cancelled` (same `cancellationKey`) cancels what is pending in every language.

Every restaurant sees all these masters and rules, in every language, in the
[Automatic messages widget](https://docs.minimo.it/embedded/widget-automatic-messages.md). There is no filter by language.

If your app already writes its emails in every language, send your own HTML with `POST /public/v1/emails`. It is
simpler: see [Senders and sending](https://docs.minimo.it/embedded/senders-and-sending.md).

## Per restaurant: switch off or change a rule

The [automatic messages widget](https://docs.minimo.it/embedded/widget-automatic-messages.md) shows each tenant an **Automatic sends** list with an on/off switch per rule. The choice is saved by Minimo for that tenant and your page receives `automation.toggled` with `{ tenant, rule, enabled }`. A send of a rule that is off is recorded as `skipped` / `disabled_by_tenant`.

By API (any field of a default can be overridden for one tenant, using the default's `key`; a key without a default is the tenant's own rule and needs `event`, `template` and the timing, with `"offset": null` for an immediate one, otherwise `422 INVALID_AUTOMATION_RULE`):

```bash theme={null}
curl -X PUT https://api.minimo.it/public/v1/tenants/restaurant_4812/automations \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rules": [ { "key": "reminder", "offset": "-P1D" }, { "key": "review", "enabled": false } ] }'
```

`GET /public/v1/tenants/{tenant}/automations` returns the tenant's effective rules (`source`: `default`, `override` or `tenant`); `DELETE /public/v1/tenants/{tenant}/automations/{key}` goes back to the default (`204`, `404` when the tenant has no override for that key).

## Limits

* Email only; one event gives one email per rule. No multi-step flows, waits or conditions (use the workspace automations for those).
* Changing a rule's offset does not move sends already planned: send the update event.
* Offsets up to one year.

## If something fails

A rule that is not valid answers `422 INVALID_AUTOMATION_RULE`: `userMessage` says which field. Every code:
[Errors and limits](https://docs.minimo.it/embedded/errors.md#templates-events-and-rules). Reference:
[Save Default Rules](https://docs.minimo.it/api-reference/embedded/rules/save-default-rules.md).

## Next step

[Booking events](https://docs.minimo.it/embedded/events.md): send the events that start the rules.


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