> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Emails

> What MarketBox sends on your behalf, when, and what you control.

MarketBox sends transactional email automatically as bookings are created, changed and completed.
You do not trigger these — creating a booking through the API is enough. This page covers every
email that exists, who receives it, and which parts you can configure.

Emails are sent from MarketBox's infrastructure under your project's name. Nothing here is a
marketing surface: there is no list, no unsubscribe funnel, and no campaign. Every message is tied
to one booking, one order or one invitation.

## The full set

> [!NOTE]
>
> All times are relative to the booking. "Start" and "end" mean the booking's scheduled start and end,
> not when it was created.

### When a booking is created

| Email | Goes to | When |
| - | - | - |
| Booking confirmation | the client | immediately |
| New booking | the assigned supplier | immediately |

Both are sent as part of the create call. A booking created without a supplier assigned sends only
the client's.

**A hold sends nothing — converting it is what sends these.** A hold only claims a supplier's time;
no booking exists yet, so there is nobody to confirm anything to. `POST /holds/{reservationId}/convert`
is the moment the booking is created, so that is when the client confirmation and the supplier notice
go out, along with everything scheduled below. If your checkout holds time while the client pays, the
client is mailed when you convert the hold — not when they reach the payment page. A
repeated convert that replays the same bookings does not re-send them. See
[Hold slots during checkout](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md).

### Before it happens

| Email | Goes to | When |
| - | - | - |
| Reminder | the client | 24 hours before start |
| Daily agenda | each supplier | 07:00 in the supplier's own timezone |

The agenda lists that supplier's bookings for the day and is the only recurring email in the system.
Suppliers with nothing booked get nothing.

### When something changes

| Email | Goes to | When |
| - | - | - |
| Booking updated | client, current supplier, previously assigned supplier, project admins | on a change to time, location or supplier |
| Booking cancelled | client, supplier, project admins | on cancellation |
| Order cancelled | the client | when an order is cancelled, listing every session it cancelled |
| Order cancelled | each supplier with a cancelled session | the same moment, listing only that supplier's sessions |
| Your booking needs a new time | the client | when the business offers new times for a booking the supplier can't make |

Cancelling a booking also removes every email still scheduled for it — no reminder, no rating
request afterwards.

**Cancelling an order sends one email per person, not one per booking.** The order's remaining
sessions are cancelled with it, and the client gets a single message listing all of them. Each
supplier gets a single message listing only their own. Project admins are not mailed. A cancel that
finds nothing left to cancel sends nothing.

The new-time offer lists the options the business proposed, each linking to the client's booking
with that option selected. Only the client receives it. The supplier hears about the move through
the usual booking-updated email once the client picks a time.

### After it happens

| Email | Goes to | When |
| - | - | - |
| Leave a rating | the client | 1 hour after end |
| Rating follow-up | the client | 3, 6 and 9 days after end |
| Rate your client | the supplier | 1 hour after end |
| Rating follow-up | the supplier | 3, 6 and 9 days after end |

Both sides are asked independently: the client is asked to rate the supplier, and the supplier to
rate the client and confirm they attended. Neither knows about the other.

### Account

| Email | Goes to | When |
| - | - | - |
| Invitation | the invited supplier or staff member | when an invitation is created or resent |

## Stopping the rating follow-ups

The follow-ups exist to chase a rating that never arrived. **They stop as soon as that side leaves
one** — a client who rates after the first email never receives the other three.

What makes that work is the review being linked to the booking. Reviews created through
`POST /v1/projects/{projectId}/bookings/{bookingId}/reviews` are linked by definition, so
suppression is automatic.

> [!WARNING]
>
> A review created through the older project-level `POST /v1/projects/{projectId}/reviews` route
> **without** a `bookingId` is not linked to any booking, so MarketBox cannot tell it happened and the
> client keeps being asked. If you use that route, always supply `bookingId`.

The two directions are tracked separately. A supplier rating a client does not stop the client's
follow-ups, and vice versa — each side is only ever chased about its own missing rating.

See [Reviews and reports](https://docs.gomarketbox.com/resources/reviews.md) for the endpoints themselves.

## Where the rating links go

The rating emails contain five star links and a button. By default they lead to a MarketBox-hosted
page where the recipient can leave their rating and confirm attendance — no login, and nothing for
you to build.

If you would rather collect ratings on your own site, set a **review redirect URL** in your
project's notification settings in the MarketBox dashboard. Every rating link then points there
instead, with the booking identified in the query string:

```
https://example.com/review?bookingId=bk_01kv60qge5eh59ap0gw0pqrrys&role=client&rating=4
```

* `bookingId` — always appended, whatever URL you configure
* `role` — `client` or `supplier`, so one page can serve both
* `rating` — present only on the star links, carrying the star that was clicked

You can also template the URL. Four tokens are substituted anywhere in the configured string,
and the query parameters above are still appended:

| Token | Resolves to | Falls back to |
| - | - | - |
| `{bookingId}` | the booking's id | — |
| `{bookingLocale}` | the language the booking was purchased in (`locale` on the booking, copied from its order) | the project's default locale |
| `{clientLocale}` | the client's `defaultLocale` — the language of their most recent booking, or a value staff set | the project's default locale |
| `{supplierLocale}` | the supplier's `defaultLocale`, staff-set | the project's default locale |

```
configured:  https://example.com/{clientLocale}/review/{bookingId}
sent:        https://example.com/fr-CA/review/bk_01kv60qge5eh59ap0gw0pqrrys?bookingId=bk_01kv60qge5eh59ap0gw0pqrrys&role=client
```

Each locale token falls back **only** to the project default, never to one of the other two —
`{supplierLocale}` can never quietly render the client's language, which is why there are three.
A token never renders empty: the project default always exists. Values are URL-encoded before
substitution, so a locale cannot inject path or query structure. Locales are recorded by sending
`locale` on `POST /v1/projects/{projectId}/orders`; see
[Orders](https://docs.gomarketbox.com/resources/orders.md#creating-an-order).

> [!TIP]
>
> Ignore query parameters you do not recognise. More may be added, and a page that validates strictly
> will break when they are.

Your page then posts to the API from your own server, using your API key. See
[Reviews and reports](https://docs.gomarketbox.com/resources/reviews.md).

## Sender identity

Three settings, all in your project's notification settings in the dashboard:

| Setting | Effect |
| - | - |
| From name | The display name on every email from this project. Defaults to the project name. |
| Reply-to address | Where replies go. Defaults to your project's first admin, so replies reach a person even if you set nothing. |
| Blind copies | Addresses that quietly receive a copy of the emails you send. Off unless you add one. |

**Who your emails come from.** The from name is what recipients see in their inbox. Leave it blank
and it is your project name.

**Where replies go.** When someone hits reply, the message goes to your reply-to address. You do
not have to set one up: with the field empty, replies go to your project's first admin
automatically. Fill the field in to send them somewhere else instead — a shared support inbox, say —
and that address takes over for every email. The only case where replies go nowhere useful is a
project with no admin and no address set: those land on the sending address, which nobody reads.

**Who gets blind-copied.** You can list up to ten addresses to receive a silent copy of every email
your project sends — handy for keeping a support or operations inbox in the loop. Recipients cannot
see these addresses, and they are not part of the conversation: replies still go to your reply-to
address.

You can also override the list for individual emails: give one kind of email its own set of
addresses, or turn blind copies off for it entirely, while everything else keeps using the main
list. Use it to keep the daily supplier agenda out of a busy inbox, or to send booking
confirmations to your accounts team instead of the main list.

> [!NOTE]
>
> Invitation emails are never blind-copied, and this cannot be changed. The link in an invitation is
> what lets someone join your project — a copy of it sitting in a shared inbox would let anyone who
> can read that inbox accept the invitation.

None of this is stored on the email itself — it is all resolved when each message is sent, so
renaming your project changes the name on the next send, including for bookings made before the
change. The same goes for changing where replies go or who is copied: it applies from the next
email onwards and does not rewrite anything already sent.

## Links in supplier emails

The supplier emails link to the MarketBox dashboard by default. When the
project has a supplier portal URL, set by a project admin under **Settings ›
Notifications › Supplier portal**, they link to your portal instead: the new
booking, booking updated, booking cancelled, order cancelled and daily agenda
emails. An email about exactly one booking adds its `bookingId` to the link.
Client emails, staff copies, the supplier's rating emails and the invitation
are unchanged. The URL can't be set through the API. See
[Supplier portal: sign-in and access](https://docs.gomarketbox.com/guides/supplier-portal-sign-in-and-access.md#links-in-marketbox-emails).

## Limits worth knowing

* **There is no per-project switch to turn emails off.** Every project on MarketBox sends the full
  set.
* **Nothing marks a booking complete automatically.** The rating emails fire on the booking's
  scheduled end time, not on a status change, so they arrive whether or not anyone updated the
  booking afterwards.
* **Cancelled bookings send nothing further**, but a booking marked as a no-show still stops the
  rating requests too.
* **Emails cannot be resent through the API.** Invitations are the exception — resending one sends a
  fresh email.


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