# Sync your Joy guest list from a spreadsheet

> Keep a shared guest sheet and your Joy guest list in step: new rows become guests with parties and tags, changed emails are updated in place.

Source: https://cotlet.dev/integrations/joy-api-mcp-server/add-guests-from-spreadsheet

The real guest list is a Google Sheet that both families keep editing, and Joy only knows the version you uploaded the first time. Every new cousin or corrected email means another round in the Guest List.

Cotlet does it in your own Joy account with list\_events, list\_guests, add\_guest, update\_guest and assign\_guest\_tags, called by your AI agent, an n8n workflow or a script.

[Request access](https://cotlet.dev/app/signup?app=joy) [All Joy tools](https://cotlet.dev/integrations/joy-api-mcp-server)

Hosted · nothing to install or maintain

Official options

## Can Joy do this on its own?

Joy has no API for guests (checked 12 Oct 2026). The only bulk path is the CSV import, which needs headers that match the template exactly, fails on a missing or misplaced column, and adds to the existing list. The Joy help center describes no way to update guests that are already on the list from a file, so every change after the first upload is made by hand in the Guest List.

By hand

## How you do it in Joy today

1. Copy the rows into Joy's Google Sheets template so every column header matches exactly and starts in the first column, then save the file as CSV.
2. In Joy, open Guest List > Add Guests > Upload Spreadsheet > Upload File and read the counts of valid, invalid and warning contacts.
3. Click Import Valid Contacts. Joy skips the invalid rows, so those get fixed in the sheet and uploaded again as a separate file.
4. Back on the Joy Guest List, group households with Create Party, set blank plus-ones in the plus ones column and add groups with Assign Tags.
5. The Joy import adds to the list rather than replacing it, so each later version of the sheet means spotting the new rows by eye and retyping changed emails cell by cell.

With an agent

## How to sync your Joy guest list from a spreadsheet

Prompt

```
Compare our "Wedding guests" Google Sheet with the Joy guest list: add the new rows as guests with their party and tags, update changed emails and phone numbers, and list anything you are not sure about.
```

1. 01  
### Match every row before writing  
The agent reads the full Joy list with list\_guests and pairs each sheet row with a guest by email first, then by first and last name. Only rows with no match count as new. A row that matches two Joy guests stops there and goes on the question list.
2. 02  
### Add the new people as households  
For each unmatched row add\_guest creates the guest with the household from your sheet as the party, so a couple lands in one party and one of them can answer for both. The envelope line comes from your address column when there is one.
3. 03  
### Fix what changed, leave RSVPs alone  
When a matched guest has a new email, phone or household in the sheet, update\_guest writes only those fields. RSVP answers in Joy are never overwritten from the sheet, because the guest gave them on the website and the sheet is older.
4. 04  
### Hold the doubtful rows  
Names with symbols, two rows with the same name and no email, and guests who are in Joy but gone from the sheet are reported, not changed. Nothing is deleted: removing a guest in Joy also drops their email tracking, so that call stays yours.
5. 05  
### Tag in one pass at the end  
Groups from the sheet ("Bride family", "Rehearsal") go on with one assign\_guest\_tags call per tag. Those tags decide who sees private events and which RSVP questions appear, so the agent lists the tag counts for you to check.

### What you get back

Example data

```
Sheet "Wedding guests": 168 rows, Joy guest list: 152 guests.
Added 14 guests in 9 parties, for example "The Okafor Family" (Chidi, Ada, 2 kids).
Updated 3 emails and 1 phone number; no RSVP answers touched.
Tagged 11 new guests "Bride family" and 6 "Rehearsal".
Not changed: "Zoë-Ann Price" has a symbol Joy rejects in names.
Not changed: two rows for "Sam Lee" without email; which one is new?
In Joy but not in the sheet: Paul Reid. Remove him yourself if he is off the list.
```

### Other ways to ask

- Add the 12 people in the "Groom side" tab to Joy, grouped by the Household column, and tag them Groom family.
- Every Sunday until invitations go out, sync the guest sheet to Joy and send me only what changed.
- Find guests in Joy who still have no email address and fill them in from the sheet where it has one.

Before you automate it

## What Joy allows, and what to know first

- Joy allows no symbols in the first or last name columns of an imported guest file, and rows Joy marks invalid are skipped by Import Valid Contacts.
- Joy expects one guest per row; a household is addressed through the Name on Envelope column, not by putting two people in one row.
- Several tags in one cell of the Joy CSV template are separated with a pipe (|), and a tag can be text or an emoji.
- Joy keeps a guest's email tracking history when two entries are merged with Merge Duplicates, but deleting the guest removes it.
- Joy needs email addresses only for eCards; online RSVPs work without them, but two guests with the same name need an email each to be told apart.

add\_guest, update\_guest and assign\_guest\_tags change only your own Joy data and reach no one else, so they run without asking first.

Sources: [Joy Help: importing and exporting your guest list](https://withjoy.com/help/en/articles/8309207-importing-and-exporting-your-guest-list) · [Joy Help: merge duplicate guests](https://withjoy.com/help/en/articles/8310170-merge-duplicate-guests) · [Joy Help: adding plus ones and parties](https://withjoy.com/help/en/articles/8343360-adding-plus-ones-and-parties) · [Joy Help: do I need guest email addresses](https://withjoy.com/help/en/articles/8320174-do-i-need-to-enter-my-guests-email-addresses-into-the-guest-list)

REST

## Call add\_guest from a script

curl

```
curl https://cotlet.dev/api/v1/joy/add_guest \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_8KQ2mZ","first_name":"Ada","last_name":"Okafor","email":"ada.okafor@example.com","party":"Okafor","name_on_envelope":"The Okafor Family","tags":["Bride family"]}'
```

Example response

```
{
"guest_id": "g_4e08",
"first_name": "Maria",
"last_name": "Porter",
"party": "Porter family",
"name_on_envelope": "The Porter Family",
"tags": [
"family"
],
"rsvp": "no_response"
}
```

MCP: add https://cotlet.dev/mcp/v1 with the same key; the tool is joy\_add\_guest. Example data.

[Schedule it in n8n, Make, Zapier or cron](https://cotlet.dev/integrations/joy-api-mcp-server#automations)

Tools

## Joy tools this automation uses

__Cotlet Joy tools used to sync your Joy guest list from a spreadsheet__
| Tool | Parameters |
| ------------------- | --------------------------------------------------------------------------------------------- |
| list\_events | none |
| list\_guests | event\_id, rsvp, tag, search, limit, cursor |
| add\_guest | event\_id, first\_name, last\_name, email, phone, party, plus\_ones, name\_on\_envelope, tags |
| update\_guest | event\_id, guest\_id, fields |
| assign\_guest\_tags | event\_id, guest\_ids, add, remove |

[All 15 Joy tools with descriptions](https://cotlet.dev/integrations/joy-api-mcp-server#tools)

## Frequently asked questions

### Can guests add their own plus-ones instead?

Yes. Joy has an Allow Any Guest to Add +1s switch under the gear icon on the Guest List page. With it on, guests state their party size when they RSVP, so the sheet does not need blank plus-ones.

## More Joy automations

- [Send Joy RSVP reminders to guests who have not replied](https://cotlet.dev/integrations/joy-api-mcp-server/send-rsvp-reminders)
- [Get final Joy meal counts and dietary notes for the caterer](https://cotlet.dev/integrations/joy-api-mcp-server/export-meal-choices)
- [Send Joy thank-you notes for registry gifts](https://cotlet.dev/integrations/joy-api-mcp-server/send-thank-you-notes)
- [Joy API and MCP server: every tool](https://cotlet.dev/integrations/joy-api-mcp-server)
- [All use cases](https://cotlet.dev/use-cases)

## Give your agent access to Joy.

Free 7-day trial with 5,000 credits, no card needed. Cotlet is independent and not affiliated with Joy.

[Request access](https://cotlet.dev/app/signup?app=joy)