> ## 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 restaurant, and the unsubscribe and preferences pages your restaurants' guests see

A restaurant's marketing email reaches only its guests who agreed, with proof of that consent. This page shows how to
record the consent and what guests see when they unsubscribe.

## Example: record a consent

Send it from your booking form, with what the guest saw and when they agreed:

```bash theme={null}
curl -X PUT https://api.minimo.it/public/v1/tenants/restaurant_4812/subscriptions \
  -H "Authorization: Bearer YOUR_MINIMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": [
      {
        "email": "giulia@example.com",
        "status": "subscribed",
        "source": "booking",
        "evidence": {
          "ref": "booking-4812",
          "consentText": "I want offers from Trattoria da Mario by email",
          "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` in the answer. Reference: [Record Guest Consent](https://docs.minimo.it/api-reference/embedded/tenants/record-consent.md).

## Two kinds of email

| Kind | Examples | Needs marketing consent | Unsubscribe footer |
| - | - | - | - |
| **Service** (utility) | 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 service template that reads like a promotion
cannot be an automatic message for restaurants (`422 MASTER_LOOKS_PROMOTIONAL` on
`PUT /public/v1/widgets/settings`).

## Consent per restaurant

Every restaurant has its own guests. The same address at another restaurant, or in your own workspace, is another
contact. So a consent always belongs to one restaurant. There is nothing to switch on.

| | A restaurant's guest | A contact of your own workspace |
| - | - | - |
| Who gets the marketing | Guests of **that restaurant** whose consent has its evidence | Contacts with marketing consent |
| What the unsubscribe link stops | That restaurant only. The page also offers to stop every email sent through your SaaS | Marketing from your workspace |
| How you record consent | The booking event with `tenant` and `marketingConsent: true`, the subscriptions call above, or the consent box in the Contacts and Campaigns widgets | `marketingConsent` on the contact, or on the booking event without `tenant` |
| How you withdraw it | `POST /public/v1/contacts/opt-out` with `tenant`, or `unsubscribed` in the subscriptions call | `POST /public/v1/contacts/opt-out` without `tenant` |

### Ways to record a consent

* The subscriptions call above: `PUT` (or `POST`) `/public/v1/tenants/{tenant}/subscriptions`, permission **Widgets**
  or **Events**, up to 500 guests per call.
* The booking event on `POST /public/v1/events` with `tenant` and `marketingConsent: true`. Put the details in
  `payload.consentEvidence`. See [Rules](https://docs.minimo.it/embedded/automations.md).
* The consent box in the [Contacts](https://docs.minimo.it/embedded/widget-contacts.md) and [Campaigns](https://docs.minimo.it/embedded/widget-campaigns.md) widgets.

A consent for one restaurant never changes what the guest agreed with another one or with your workspace.
`marketingConsent: true` on `POST /public/v1/contacts` with `tenant` is refused (`422 TENANT_CONSENT_NEEDS_EVIDENCE`):
a consent without evidence would not count.

### Subscriptions API

* `source`: where the consent was collected: `booking`, `api` (the default) or `import`. Any other value answers
  `400 INVALID_PARAMETERS`. To record the name of your form, use `evidence.consentVersion`.
* Every `evidence` needs `ref`. An `evidence` without `ref` fails the whole call with `400 INVALID_PARAMETERS` and
  nothing is saved.
* `outcome` per guest: `subscribed`, `unsubscribed`, `unchanged`, `skipped_opted_out` (unsubscribed earlier, no newer
  consent), `contact_not_found` or `invalid` (with `error`, for example a subscription without `evidence`).
* A guest new to the restaurant is created as its guest, with the consent and its evidence.
* `GET /public/v1/tenants/{tenant}/subscriptions?email=…` returns one guest's status, evidence and
  `canReceiveMarketing`. Reference: [Get Guest Consent](https://docs.minimo.it/api-reference/embedded/tenants/get-consent.md).

## What Minimo checks when it sends

* A marketing email goes only to a guest of that restaurant whose consent has its evidence. Everyone else is skipped,
  at send time and again when a scheduled email is due.
* A single send to someone else is refused and nothing is sent: `422 MARKETING_CONSENT_REQUIRED` (not a guest, or no
  consent) or `422 TENANT_SUBSCRIPTION_REQUIRED` (the guest agreed, but without evidence). Record the consent first.
* Every marketing email of a restaurant has the unsubscribe footer and the one-click `List-Unsubscribe` header.
* 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 rules check consent again when a marketing email is due. A guest who unsubscribed meanwhile is skipped
  (`no_marketing_consent`).
* Service emails are never blocked by consent.

## Unsubscribes, complaints, bounces

* The unsubscribe link and the mailbox unsubscribe button stop **that restaurant only**. The page names the
  restaurant, shows its data controller, and offers to stop every email sent through your SaaS (every restaurant and
  your workspace) for that address.
* A guest who unsubscribed can be subscribed again only with a consent given **later** (`evidence.consentedAt`). The
  widgets never subscribe them again.
* A spam complaint about a restaurant's email stops that restaurant's marketing to that guest and counts against the
  restaurant (see [protections](https://docs.minimo.it/embedded/protections.md)).
* A bounce makes the address dead for everyone.

## The pages guests see

The unsubscribe link of every email opens a page hosted by Minimo, in English or Italian. The language comes from the
text of the email, not from the restaurant:

* Minimo reads the subject and the text and looks for common words of a language (at least 3).
* A short email, or one with few such words, gets an English footer and an English page. Write your Italian templates
  with full sentences.
* Any language other than Italian gives an English page.

What the page shows:

* **The restaurant's** name, logo, color and data controller (from the
  [tenant profile](https://docs.minimo.it/embedded/widget-brand.md#tenant-profile)), never your SaaS's branding.
* A confirm button and an optional reason. The mailbox unsubscribe button (the `List-Unsubscribe` header) works
  without the page. There is no one-click "subscribe again" on the success page.
* The **preferences** page shows that restaurant only: who can write to the guest, then the channels (Email, WhatsApp,
  SMS). Empty contact fields are hidden. These switches change nothing at other restaurants or in your workspace.

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

## If something fails

On a workspace without embedded widgets the subscriptions endpoints answer `409 TENANT_CONSENT_NOT_ENABLED`: save the
[widget settings](https://docs.minimo.it/embedded/quickstart.md) first, or use the contact's `marketingConsent` and
`POST /public/v1/contacts/opt-out`. Every other code: [Errors and limits](https://docs.minimo.it/embedded/errors.md).

## Next step

[Protections and sending limits](https://docs.minimo.it/embedded/protections.md)


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