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

# Consent, unsubscribe and preferences

> Service emails vs marketing, consent per workspace or per restaurant, and the unsubscribe and preferences pages your restaurants' guests see

## Two kinds of email

| Kind | Examples | Needs marketing consent | Unsubscribe footer |
| - | - | - | - |
| **Utility** (service) | Booking confirmation, reminder, cancellation | No, never blocked by consent | As set in the template |
| **Marketing** | Review request, offer, newsletter, every campaign | Yes | Always, with the one-click `List-Unsubscribe` header |

The category is set on the template. A review request is marketing: a utility template that reads like a promotion cannot be exposed to restaurants as an automatic message (`422 MASTER_LOOKS_PROMOTIONAL` on `PUT /public/v1/widgets/settings`).

## Rules in a workspace that sends for tenants

* A marketing template only goes to an **existing contact with email marketing consent**. An unknown address or a contact without consent is refused: nothing is sent, no contact is created, and the send answers `422 MARKETING_CONSENT_REQUIRED`. Add the guest with `marketingConsent` first (or with the booking event, see below). Utility templates are not affected.
* Every marketing email of a restaurant carries the unsubscribe footer and the one-click `List-Unsubscribe` header. Withdrawals are recorded by Minimo, on the same page and endpoint for every restaurant.
* In the editor a restaurant cannot remove the footer, hide the sender identity line or replace the email with HTML that drops the unsubscribe link (`422 TENANT_FOOTER_REQUIRED`).
* The automatic rules check consent again when a marketing email is due: a guest who unsubscribed in the meantime is skipped (`no_marketing_consent`).

## Consent per workspace or per restaurant

| | Per workspace (default) | Per restaurant |
| - | - | - |
| Who can receive a restaurant's marketing | Guests with marketing consent in your workspace (a campaign: only the restaurant's own contacts) | Guests **subscribed to that restaurant**, with evidence, and not unsubscribed from your workspace |
| What the unsubscribe link stops | Marketing from your whole workspace | That restaurant only; the page offers "also unsubscribe from every email sent through" your SaaS |
| How you record consent | `marketingConsent` on the contact, or on the booking event | The booking event with `tenant` + `marketingConsent: true`, the subscriptions API, or the consent box in the Campaigns widget |
| How you withdraw it | `POST /public/v1/contacts/opt-out` | Same endpoint with `tenant` (that restaurant only), or `unsubscribed` in the subscriptions API |

Every workspace starts **per workspace**. Minimo switches an embedded workspace to **per restaurant** on request: ask before your first real restaurant if your restaurants collect consent separately (for example a box "I want offers from Trattoria da Mario" in the booking form).

## Consent per restaurant

When your workspace keeps consent per restaurant:

* **Who receives a restaurant's marketing email** (campaign, marketing template such as the review request, automatic message with a marketing template): only guests subscribed to **that restaurant**, with evidence of their consent, and who have not unsubscribed from your workspace. Everyone else is skipped, at send time and again when a scheduled email fires. A 1:1 send to a guest who is not subscribed answers `422 TENANT_SUBSCRIPTION_REQUIRED`. Utility emails are never affected.
* **How a subscription is recorded**: when a restaurant adds a guest in the Campaigns widget with the consent box ticked; when your booking event on `POST /public/v1/events` carries `tenant` and `marketingConsent: true` (put the details in `payload.consentEvidence`); or with the subscriptions API below. Recording a consent for one restaurant never changes what the guest agreed with another one.
* **Unsubscribe**: the link and the mailbox unsubscribe button of a restaurant's email stop that restaurant only. The page names the restaurant, shows the data controller and offers to also unsubscribe from every email sent through your SaaS, which stops every restaurant. The preferences page lists the restaurants the guest is subscribed to and lets them leave one.
* **Spam complaints** stop marketing from your whole workspace for that guest, and count against the restaurant (see [protections](https://docs.minimo.it/guides/embedded-protections.md)).
* **After an unsubscribe**, a guest can be subscribed again only with a consent given later than the unsubscribe (`evidence.consentedAt`). The widget never subscribes them again.

### Subscriptions API

`PUT /public/v1/tenants/{tenant}/subscriptions` (also `POST`), permission `widgets` or `events`, up to 500 guests per call:

```json theme={null}
{
  "subscriptions": [
    {
      "email": "giulia@example.com",
      "status": "subscribed",
      "source": "booking",
      "evidence": {
        "ref": "booking-4812",
        "consentText": "Voglio ricevere offerte da Trattoria da Mario",
        "consentVersion": "booking-form-v3",
        "ip": "203.0.113.7",
        "userAgent": "Mozilla/5.0 ...",
        "consentedAt": "2026-11-08T19:30:00+01:00"
      }
    },
    { "email": "marco@example.com", "status": "unsubscribed", "reason": "Unticked in the booking form" }
  ]
}
```

Each guest gets an `outcome`: `subscribed`, `unsubscribed`, `unchanged`, `skipped_opted_out` (unsubscribed earlier, no newer consent), `contact_not_found` or `invalid` (with `error`; a subscription needs `evidence.ref`). A guest new to your workspace is created with email marketing consent. `GET /public/v1/tenants/{tenant}/subscriptions?email=…` returns one guest's status, evidence and `canReceiveMarketing`.

In a workspace with consent per workspace these endpoints answer `409 TENANT_CONSENT_NOT_ENABLED`, with a message that says to use the contact's `marketingConsent` and `POST /public/v1/contacts/opt-out` instead.

## The pages guests see

The unsubscribe link of every email opens a page hosted by Minimo, in the email's language:

* For a restaurant's email it shows **the restaurant's** name, logo and color (from the [tenant profile](https://docs.minimo.it/guides/embedded-widget-brand.md#tenant-profile)) and its data controller, never your SaaS's branding.
* The guest confirms on the page and can pick a reason. The unsubscribe button of the mailbox (the `List-Unsubscribe` header) works without the page. There is no one-click "subscribe again" on the success page.
* The **preferences** page shows who can write to the guest first, then the channels, and hides contact fields that are empty.

Nothing to build on your side: set the restaurant's display name, logo and legal details in the tenant profile (or let the restaurant set them in the [Brand widget](https://docs.minimo.it/guides/embedded-widget-brand.md)) and the pages follow.


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