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

# Message event guests

> Email one group of a Cal Event's guests from the Guests board, then track each message's delivery and retry failed sends from Message history.

Hosts can send a one-off email to the guests of a Cal Event, for example to share a venue change,
say the doors are open, or send a link to the recording afterwards. Every message is listed under
**Message history**, with who sent it, when, which guests it went to and how delivery went.

![The Message history panel on a Cal Event's Guests board, listing messages newest first with their sender, time, group, status and delivery counts](https://mintcdn.com/calcom/U68BNx1kj3u0wSkh/images/event-blasts/message-history-list.png?fit=max\&auto=format\&n=U68BNx1kj3u0wSkh\&q=85\&s=c4e5ea2941610e94cd058065273d711f)

## Who can message guests

**Message guests** and **Message history** appear on the event's Guests board for:

* The event's hosts
* Team members whose role lets them edit the team's events
* The owner of a personal event

External co-hosts don't see either button. Anyone who can message an event's guests sees every
message sent on that event, whoever sent it, and can retry any of them.

## Send a message

**1. Open the Guests board**

Go to **Events**, open the event, and select **Attendance** → **Guests**.

**2. Open Message guests**

Select **Message guests** in the toolbar. On a phone, select **Message guests** in the bar at the
bottom of the screen instead. It's there on every tab of a published event and takes you to
**Guests**.

![A published Cal Event open in the editor on a phone, with Message guests, a more actions button and a round add button in the bar at the bottom of the screen](https://mintcdn.com/calcom/U68BNx1kj3u0wSkh/images/event-blasts/mobile-bottom-nav.png?fit=max\&auto=format\&n=U68BNx1kj3u0wSkh\&q=85\&s=b43b2d6d3ce1cbf93887962a1e2cd113)

**3. Choose who gets it**

Under **Send to**, pick one group: **Going**, **Maybe** or **Pending**. On desktop the dialog
opens on **Going**; on a phone it opens on the group you're filtering by. The dialog shows how many
guests will get the email.

**4. Narrow it down (optional)**

Use **Check-in** to send only to guests who have **Checked in** or are **Not checked in**; leave
it on **Any** to include both. If the event has more than one location, you can also pick one
under **Location** to send only to guests who chose it, or leave it on **All locations**. The
dialog opens on the location the Guests board is filtered by, and the guest count updates to
match your choices.

**5. Write the message**

Enter a **Subject** and a **Message**. Messages are plain text; paste links as plain URLs.

**6. Send now or later**

Under **When**, leave **Send now** selected to send straight away, or choose **Send later** to
pick a date and time. See [Send a message later](#send-a-message-later).

**7. Send**

Select **Send**, or **Schedule** if you chose a time. For a message sent now, a toast shows its
status while it goes out.

![The Message guests dialog with Going selected, Location set to In person · Hall A and Check-in set to Not checked in, showing that 3 guests will get the email](https://mintcdn.com/calcom/zd5UoAZueJwtKZ0w/images/event-blasts/message-guests-location-check-in.png?fit=max\&auto=format\&n=zd5UoAZueJwtKZ0w\&q=85\&s=78becfc82bacc195e675a70efa075b5b)

| Group | Who receives it |
| - | - |
| **Going** | Confirmed guests who RSVP'd yes, and the event's accepted co-hosts |
| **Maybe** | Confirmed guests who RSVP'd maybe |
| **Pending** | Guests awaiting approval, on the waitlist or with a payment pending |

When you send to **Going** without choosing a **Location** or **Check-in** option, the event's
accepted co-hosts get the message too, and the guest count includes them. Their email has no
unsubscribe link. A co-host who also registered as a guest gets it only if their registration is in
the group. Co-hosts aren't added to **Maybe** or **Pending**, and the event's hosts aren't added to
any group.

Invited people who haven't RSVP'd, and guests who declined or cancelled, can't be messaged.
**Location** and **Check-in** only narrow the group you picked, so they never add guests from
outside it. Only confirmed guests can check in, so **Pending** with **Checked in** has no one to send to.

> [!NOTE]
>
> Pending guests aren't admitted yet, so their email doesn't include the venue or join link.

Some guests in the chosen group don't receive the email:

* **Guests who RSVP'd by phone** have no email address, so they're skipped. The dialog tells you how
  many before you send.
* **Guests who unsubscribed** from host messages for the event are skipped. Guests can unsubscribe
  from the link in a host message; they stay registered and still get essential updates, like a time
  change or a cancellation.

Messages are sent to the guests who are in the group when sending starts. Guests who register, and
co-hosts who accept their invitation, after you select **Send** don't receive it.

You can also ask the [Cal.com assistant](https://cal.com/docs/agents.md#email-a-cal-events-guests-through-the-assistant) to
message one group of guests, narrowed by location or check-in in the same way. It shows the group,
the guest count, the subject and the message on an approval card, and sends only after you approve.

## Send a message later

Choose **Send later** under **When** to send the message at a time you pick, for example an hour
before doors open. Select the date and time; they're in the event's time zone, which the dialog
shows under the picker, and the dialog confirms when the message will be sent. Then select
**Schedule**.

The time has to be at least 5 minutes from now and no later than 7 days after the event ends.
Everything else works as for a message sent now, with one difference: the guests are worked out when
the message goes out, not when you schedule it. Someone who registers before then gets it, and
someone who unsubscribes before then doesn't. If the event is cancelled or unpublished before the
time, nothing is sent.

A scheduled message shows in **Message history** as **Scheduled for** its time. Open it to read its
**Subject** and **Message**, with its line breaks, and check what will go out. To cancel it, select
**Cancel message**. You can cancel until its time arrives. A cancelled message is never sent, and
guests aren't told.

![The details of a scheduled message in Message history, showing the sender, group, date, a Scheduled for status, and the message's subject and text, with Back and Cancel message buttons](https://mintcdn.com/calcom/soq70L2ckel-B_uu/images/event-blasts/scheduled-message-detail.png?fit=max\&auto=format\&n=soq70L2ckel-B_uu\&q=85\&s=00f4317062b858aae5a8868051ac2e61)

## View message history

Select **Message history** next to **Message guests** on the Guests board. On a phone, select
**⋯** in the bar at the bottom of the screen, then **Message history**. The panel lists the event's
messages newest first, 20 at a time; select **Load more** to see older ones. If nothing has been
sent yet, the panel says **No messages sent yet**.

![The more actions menu on a phone, listing Message history, Check-in mode and Download guest list above the event's page, link, share and cancel actions](https://mintcdn.com/calcom/U68BNx1kj3u0wSkh/images/event-blasts/mobile-bottom-nav-drawer.png?fit=max\&auto=format\&n=U68BNx1kj3u0wSkh\&q=85\&s=cf507da9f833a890cc553cda18dc76fe)

Each row shows:

* The sender's name (**Deleted user** if their account has been deleted, **Unnamed user** if they
  have no name)
* When the message was sent
* The group it went to: **Going**, **Maybe** or **Pending**
* Its status
* Once sending has finished and at least one guest received it, the counts on one line: sent,
  failed, skipped by phone and unsubscribed

Select a row to open its details: who sent it, the group, the date, the status and each count.
A message still waiting for its scheduled time also shows its subject and message text. Once its
time arrives, or for any other message, the subject and message text aren't shown, and no message
shows its location or check-in choice.

![The details of a partially sent message, showing the sender, group, date, a Sent to 36 of 39 guests status, the sent, failed and skipped counts, and a Try again button](https://mintcdn.com/calcom/U68BNx1kj3u0wSkh/images/event-blasts/message-history-detail.png?fit=max\&auto=format\&n=U68BNx1kj3u0wSkh\&q=85\&s=a62b1e158e95b0a73a0ba100cace1b53)

### Statuses

| Status | Meaning |
| - | - |
| **Scheduled for (date and time)** | The message is waiting for its time. Nothing has been sent. You can cancel it. |
| **Cancelled** | You cancelled the message before its time. Nothing was sent. |
| **Sending…** | The message is going out. No counts are shown yet. |
| **Sent to N guests** | Every guest in the group with an email address received it, apart from any skipped guests. |
| **Sent to N of M guests** | Some guests received it, and the email to others failed. |
| **Not sent** | No guest received it. |
| **Not sent. This event can no longer be messaged.** | The event was cancelled or unpublished, or its messaging window closed, before anyone received the message. |

| Count | Meaning |
| - | - |
| **Sent** | Guests the email was delivered to |
| **Failed** | Guests the email couldn't be sent to |
| **Skipped, RSVP'd by phone** | Guests in the group without an email address |
| **Skipped, unsubscribed** | Guests who unsubscribed from host messages for the event |

## Retry a failed message

When a message reads **Sent to N of M guests** or **Not sent**, its details may show **Try again**.
Select it to send the message again. Guests who already received the message don't get a second
copy. The group is checked again, with the same location and check-in choices, so guests who were
already registered and have since moved into it, for example by being approved, can receive it;
guests who registered after the original send still don't. The row then reads **Sending…** and updates on its own until sending finishes.

**Try again** isn't offered when:

* The message was sent, is still sending, or is waiting for its scheduled time
* The message reads **Not sent. This event can no longer be messaged.**
* The message is more than 30 days old, counted from its scheduled time if it had one
* The message has already been retried the maximum number of times

A retry is refused if the event can no longer be messaged, or if the group no longer has any guests
with an email address or now has more than 1,000. Retrying doesn't count toward the daily sending
limits.

## Send and list messages with the API

You can also message an event's guests and list its sent messages with
[API v2](https://cal.com/docs/api-reference/v2/introduction.md). Both endpoints follow the same access rules as the Guests
board, so co-hosts can't use them, and sends count toward the same daily limits.

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v2/events/{uuid}/messages` | Email one group of guests. Send a `segment` (`GOING`, `MAYBE` or `PENDING`), a `subject` and a `body`, and optionally a `locationId` or `checkedIn` (`true` or `false`) to narrow it down. |
| `GET` | `/v2/events/{uuid}/messages` | List the event's messages, newest first, with each one's `segment`, `createdAt`, `sender`, `status` and `counts`. |

A send returns the message's `id`, a `status` of `QUEUED` (or `FAILED_TO_QUEUE` if nothing could be
sent), `recipientCount`, the number of guests and co-hosts who'll be emailed, and `skippedPhoneCount`, the number
skipped because they RSVP'd by phone. The message then goes out in the background; list the event's
messages to follow it. In the list, `status` is `SENDING`, `SENT`, `PARTIALLY_SENT`, `NOT_SENT` or
`NOT_SENT_EVENT_UNSENDABLE`, matching the statuses above. `counts` is filled in only for `SENT` and
`PARTIALLY_SENT`; it's `null` while the message is sending and whenever nothing was delivered. To
get the next page, pass `pagination.nextCursor` from the previous response as the `cursor` query
parameter.

With an OAuth access token, sending needs the `EVENT_WRITE` scope and listing needs `EVENT_READ`.
Retrying a message is only available from **Message history** on the Guests board.

## Limits

* You can message an event's guests while it's published and not cancelled, until 7 days after it
  ends.
* A message can go to at most 1,000 guests with an email address. If the group is larger, **Send**
  is disabled.
* The subject can be up to 200 characters and the message up to 5,000 characters. HTML and script
  links aren't allowed.
* Each person can send up to 20 messages a day, and each event can have up to 5 messages sent a day.


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