Sync your Joy guest list from a spreadsheet

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.

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.

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.

• 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 · Joy Help: merge duplicate guests · Joy Help: adding plus ones and parties · Joy Help: do I need guest email addresses

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"]}'

{
  "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.

• Send Joy RSVP reminders to guests who have not replied
• Get final Joy meal counts and dietary notes for the caterer
• Send Joy thank-you notes for registry gifts
• Joy API and MCP server: every tool
• All use cases