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

# Booking events

> Tell Minimo when a booking is created, changed or cancelled. The rules send, move or cancel the emails

Send an event each time a booking is created, changed or cancelled. The [rules](https://docs.minimo.it/embedded/automations.md) decide which
emails go out and when.

## Send events (your backend)

```bash theme={null}
curl -X POST https://api.minimo.it/public/v1/events \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "booking.created",
    "tenant": "restaurant_4812",
    "email": "anna@example.com",
    "firstName": "Anna",
    "idempotencyKey": "booking-9921-created",
    "cancellationKey": "booking-9921",
    "from": "Trattoria da Mario <prenotazioni@trattoriadamario.yoursaas.example>",
    "replyTo": "owner@trattoriadamario.example",
    "marketingConsent": true,
    "payload": {
      "booking_at": "2026-11-20T20:30:00+01:00",
      "GUEST_NAME": "Anna",
      "BOOKING_DATE": "venerdì 20 novembre",
      "BOOKING_TIME": "20:30",
      "PARTY_SIZE": 4
    }
  }'
```

When the booking changes or is cancelled, send the same `cancellationKey`. In a `booking.updated`, send the **full
booking**, not only what changed: its payload replaces the details of the pending emails.

```json theme={null}
{ "event": "booking.updated", "tenant": "restaurant_4812", "email": "anna@example.com",
  "idempotencyKey": "booking-9921-updated-2", "cancellationKey": "booking-9921",
  "payload": { "booking_at": "2026-11-21T21:00:00+01:00", "GUEST_NAME": "Anna",
               "BOOKING_DATE": "sabato 21 novembre", "BOOKING_TIME": "21:00", "PARTY_SIZE": 6 } }
```

```json theme={null}
{ "event": "booking.cancelled", "tenant": "restaurant_4812", "email": "anna@example.com",
  "idempotencyKey": "booking-9921-cancelled", "cancellationKey": "booking-9921" }
```

| Field | Notes |
| - | - |
| `tenant` | Your customer. Its own rules apply on top of the defaults; the guest is the contact of that tenant (created there when new), never a contact of your workspace. |
| `idempotencyKey` | Your unique id of this event. Sent again (a retry), it is recognised: nothing is sent or scheduled twice, the response says `"status": "duplicate"`. |
| `cancellationKey` | Groups the sends of one object, e.g. the booking id. Even without an `idempotencyKey`, one rule never schedules twice for the same key. |
| `payload` | Any JSON. Every value is a merge variable of the email, by its path in capitals (`GUEST_NAME`, `booking.time` → `BOOKING_TIME`), over the [tenant profile](https://docs.minimo.it/embedded/widget-brand.md#tenant-profile) (`RESTAURANT_NAME`, `LOGO_URL`, `RESTAURANT_ADDRESS`). |
| dates | **Always with the UTC offset** (`2026-11-20T20:30:00+01:00` or `…Z`). A date-time without offset is refused (`422 INVALID_EVENT_DATE`): Minimo cannot guess the restaurant's timezone. Send display values (`BOOKING_TIME`) next to the machine one. |
| `from`, `replyTo` | Sender and Reply-To of the emails of this event, checked now and again at send time (same rules as the [per-send sender](https://docs.minimo.it/embedded/senders-and-sending.md)). |
| `marketingConsent` | `true` records the guest's marketing consent to that restaurant, also for a guest who already exists, with the event as evidence. Add details in `payload.consentEvidence` (`ip`, `userAgent`, `consentText`, `consentVersion`, `legalBasis`, `consentedAt`). An event never withdraws a consent; a guest who unsubscribed is subscribed again only with a `consentedAt` after the withdrawal. See [consent](https://docs.minimo.it/embedded/consent.md). |

The response (`202`) tells you what was planned:

```json theme={null}
{
  "data": {
    "event": "booking.created", "status": "no_automation", "automations": 0, "contactId": 4521,
    "tenantAutomations": {
      "scheduled": [
        { "id": 41, "rule": "confirmation", "status": "pending", "reason": null, "sendAt": "2026-11-08T18:00:01.000Z" },
        { "id": 42, "rule": "reminder", "status": "pending", "reason": null, "sendAt": "2026-11-20T17:30:00.000Z" },
        { "id": 43, "rule": "review", "status": "pending", "reason": null, "sendAt": "2026-11-20T21:30:00.000Z" }
      ],
      "cancelled": 0, "rescheduled": 0
    }
  }
}
```

Read `tenantAutomations`: it lists what was scheduled for the restaurant. The top-level `status` and `automations`
are about a different feature (workspace automations started by an event) and can say `no_automation` even when
emails were scheduled.

## What happens at send time

Nothing decided when the event arrived is trusted when the email is due. Minimo checks again that the rule still exists and is on for the tenant, that the guest still exists and did not hard-bounce, that the template is there, that the sender is still allowed and, for a marketing template such as the review request, that the guest has marketing consent and the workspace is not on a marketing hold. The unsubscribe footer and `List-Unsubscribe` header apply as for every send.

A send that does not go out is never an error to you: it is recorded with a reason.

| Status | Reason |
| - | - |
| `pending` | Waiting for its time. |
| `sent` | Delivered to the email provider (see the [send history](https://docs.minimo.it/embedded/widget-history.md)). |
| `skipped` | `disabled_by_tenant`, `disabled`, `past_due` (its time passed by more than 5 minutes, e.g. a booking made 1 hour ahead with a 2-hour reminder), `rule_deleted`, `contact_deleted`, `suppressed`, `template_missing`, `sender_not_allowed`; for marketing templates also `no_marketing_consent`, `no_tenant_subscription` ([consent per tenant](https://docs.minimo.it/embedded/consent.md#consent-per-restaurant)), `marketing_send_on_hold`, `tenant_on_hold`, `tenant_daily_cap_reached` ([protections](https://docs.minimo.it/embedded/protections.md)). |
| `cancelled` | `cancelled_by_event:booking.cancelled`, `cancelled_by_api`, `rescheduled`. |
| `failed` | Not sent: the provider refused it, or `empty_subject` (the template has no subject line). |

```bash theme={null}
# What is planned or happened for one booking
curl "https://api.minimo.it/public/v1/scheduled-sends?cancellationKey=booking-9921" \
  -H "Authorization: Bearer YOUR_MINIMO_KEY"

# Cancel everything still pending for it (same as the cancelling event)
curl -X DELETE "https://api.minimo.it/public/v1/scheduled-sends?cancellationKey=booking-9921&tenant=restaurant_4812" \
  -H "Authorization: Bearer YOUR_MINIMO_KEY"
```

## If something fails

A date without its UTC offset answers `422 INVALID_EVENT_DATE`. A wrong `tenant` or field answers
`400 INVALID_PARAMETERS`. A send that does not go out is not an error: read its reason in
`GET /public/v1/scheduled-sends`. Every code: [Errors and limits](https://docs.minimo.it/embedded/errors.md). Reference:
[Send Event](https://docs.minimo.it/api-reference/embedded/events/send-event.md).

## Next step

[Schedule one email yourself](https://docs.minimo.it/embedded/schedule-email.md), if your backend already knows when an email must go out.


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