Managing Invitees

Learn how to work with event invitees, send invitations, and track responses.

Adding Invitees

Invitees can be added when creating or updating an event:

{
  "title": "Team Meeting",
  "startTime": "2026-01-20T14:00:00Z",
  "endTime": "2026-01-20T15:00:00Z",
  "sendEmailReminders": true,
  "invitees": [
    { 
      "email": "john@example.com", 
      "name": "John Doe",
      "isOptional": false 
    }
  ]
}

Invitee Fields

Invitation Emails

When sendEmailReminders: true, Solo automatically sends invitation emails:

What Invitees Receive

1. Email Subject: "Invitation: {event title}"
2. Email Body: Event details (date, time, location, description)
3. ICS Attachment: Clickable calendar file for easy import

Email Branding

Invitation emails use your identity's branding configuration:

• From Name: Formatted according to your fromAliasFormat setting
• Email Template: Applied if you've selected one in identity settings
• Brand Colors: Used in the email template
• Agent Signature: Included if event has an associated agentId

Example Invitation Email

Subject: Invitation: Team Standup
From: "John from Acme Inc" <john@solomail.io>

Hi Jane,

John from Acme Inc has invited you to:

📅 Team Standup
━━━━━━━━━━━━━━━━━━━━━━

📆 Date: Monday, January 20, 2026
🕐 Time: 9:00 AM - 9:30 AM (America/New_York)
📍 Location: Conference Room A
🎥 Zoom: https://zoom.us/j/123456789

Description:
Daily standup to sync on progress and blockers.

━━━━━━━━━━━━━━━━━━━━━━
This invitation was sent via Solo (https://solomail.io).
You can add this event to your calendar using the attached .ics file.

[invite.ics attachment]

Updating Event with Invitees

When you update an event, you can choose whether to notify existing invitees:

Adding New Invitees Only

By default, only new invitees receive invitation emails:

curl -X PATCH https://solomail.io/api/v1/calendar/events/{eventId} \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "invitees": [
      { "email": "existing@example.com", "name": "Existing Person" },
      { "email": "newperson@example.com", "name": "New Person" }
    ]
  }'

Result: Only newperson@example.com receives an invitation.

Notifying All Invitees of Changes

To send update notifications to ALL invitees (for time changes, etc.):

curl -X PATCH https://solomail.io/api/v1/calendar/events/{eventId} \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2026-01-20T10:00:00-05:00",
    "notifyAttendeesOfChanges": true
  }'

Result: All invitees receive "Updated: {event title}" emails.

Update Email Behavior Summary

Tracking RSVP Responses

Each invitee has a responseStatus field:

Viewing Invitee Responses

When fetching an event, include includeInvitees=true:

curl https://solomail.io/api/v1/calendar/events/{eventId}?includeInvitees=true \
  -H "Authorization: Bearer <your-api-key>"

Response:

{
  "event": {
    "id": "event-uuid",
    "title": "Team Meeting",
    "invitees": [
      {
        "id": "invitee-uuid",
        "email": "john@example.com",
        "name": "John Doe",
        "responseStatus": "accepted",
        "isOptional": false,
        "isOrganizer": false
      },
      {
        "id": "invitee-uuid-2",
        "email": "jane@example.com",
        "name": "Jane Smith",
        "responseStatus": "needs_action",
        "isOptional": true,
        "isOrganizer": false
      }
    ]
  }
}

RSVP Endpoint

Invitees with Solo accounts can respond to invitations:

curl -X POST https://solomail.io/api/v1/calendar/events/{eventId}/rsvp \
  -H "Authorization: Bearer <invitee-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "response": "accepted"
  }'

Response Values: accepted, declined, tentative

Removing Invitees

To remove invitees, update the event with a new invitees array that excludes them:

curl -X PATCH https://solomail.io/api/v1/calendar/events/{eventId} \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "invitees": [
      { "email": "remaining@example.com", "name": "Remaining Person" }
    ]
  }'

Note: Removing an invitee does not automatically send a cancellation. To notify removed invitees, you may want to:

1. Update event status to cancelled with notifyAttendeesOfChanges: true, or
2. Send a manual notification before removing them

Best Practices

1. Always include names: Invitee names make calendar entries more readable
2. Use sendEmailReminders: Set to true when you want invites sent
3. Specify timezone: Always include timezone for accurate scheduling
4. Use notifyAttendeesOfChanges: Enable for significant updates (time, location changes)
5. Check availability first: Use /calendar/availability before scheduling

---

Next: See the full Calendar API Reference