Source: https://cli.nylas.com/guides/create-calendar-invites-cli

# Create Calendar Invites from the CLI

Create a calendar invite from scripts and terminal workflows without writing provider-specific calendar API code or hand-rolling an ICS attachment.

Written by [Qasim Muhammad](https://cli.nylas.com/authors/qasim-muhammad) Staff SRE

Reviewed by [Qasim Muhammad](https://cli.nylas.com/authors/qasim-muhammad)

Updated May 15, 2026

> **TL;DR:** Use [`nylas calendar events create`](https://cli.nylas.com/docs/commands/calendar-events-create) with `--participant` for each attendee. The provider creates the event and sends the invite.

## Why not generate an ICS file yourself?

An ICS file is fine for a static event download, but most app workflows need more: attendee status, provider notifications, updates, cancellations, rooms, busy state, and calendar ownership. A provider-created event keeps those details inside the calendar system instead of turning your app into a calendar client.

Nylas CLI wraps the event creation step with [`nylas calendar events create`](https://cli.nylas.com/docs/commands/calendar-events-create), which works across connected calendar providers.

## 1. Create a basic calendar invite

Use `--title`, `--start`, and `--end` for the event window. Add one `--participant` flag per attendee.

```bash
nylas calendar events create "$NYLAS_GRANT_ID" \
  --title "Customer onboarding" \
  --start "2026-05-20T16:00:00Z" \
  --end "2026-05-20T16:30:00Z" \
  --participant customer@example.com \
  --participant csm@example.com \
  --location "Google Meet" \
  --description "Onboarding kickoff and next steps" \
  --json
```

Use UTC timestamps in automation. For local interactive scheduling, the CLI also accepts common date and time formats, but UTC is easier to test.

## 2. Set the event state

Calendar invites should usually block time. Pass `--busy` for normal meetings and `--free` for reminders or FYI holds that should not block scheduling.

```bash
nylas calendar events create "$NYLAS_GRANT_ID" \
  --title "Release window" \
  --start "2026-05-21T14:00:00Z" \
  --end "2026-05-21T15:00:00Z" \
  --participant engineering@example.com \
  --busy \
  --json
```

## 3. Check availability first

For user-facing scheduling, run [`nylas calendar availability check`](https://cli.nylas.com/docs/commands/calendar-availability-check) before creating the invite. That keeps your script from sending a meeting into a known conflict.

```bash
nylas calendar availability check "$NYLAS_GRANT_ID" \
  --emails customer@example.com,csm@example.com \
  --start "2026-05-20T16:00:00Z" \
  --end "2026-05-20T16:30:00Z" \
  --json
```

## When should you still use ICS?

Use ICS when the recipient only needs a downloadable file or when your system cannot create provider events. Use Nylas CLI when you want the connected calendar provider to own the event, send notifications, track attendee responses, and support later changes.

## What changes when the provider creates the event?

A provider-created event becomes part of the calendar system immediately. The organizer can update it, attendees can respond, and the provider can send notifications using the recipient's normal calendar experience. That is different from attaching an ICS file to an email. An ICS file can add an event to a calendar, but it leaves more behavior to the recipient and mail client.

When your workflow creates the event through a connected account, your app can store the event ID and treat it as a real object. Later automation can update the time, change the description, add a participant, or cancel the event through the same calendar surface. That makes the invite easier to manage after the first email leaves your system.

This matters for customer calls, interviews, onboarding sessions, incident reviews, release windows, and internal handoffs. Those meetings are rarely static. People reschedule, rooms change, notes get added, and attendees decline. A real calendar event gives the system a durable handle instead of a one-time attachment.

## How should you model attendees and organizers?

Choose the organizer account before creating the invite. The organizer is the calendar owner whose account sends the event and owns later updates. For a support handoff, that may be a shared support calendar. For sales, it may be the account executive. For recruiting, it may be a recruiting calendar rather than an individual interviewer.

Pass required attendees as participants. If your product has optional attendees, decide whether they should receive the initial invite or be added only after the meeting is confirmed. Many workflows book with required people first, then notify optional observers separately. This keeps scheduling from failing because one optional person has a conflict.

Keep attendee email addresses canonical. If the customer entered a typo, the provider may still create the event but the invite will not reach the right person. Validate addresses before event creation and store the normalized recipient list next to the event ID. That record makes it easier to reconcile attendee responses later.

## What should go into the invite body?

The invite body should be short, specific, and useful without opening your app. Include the meeting purpose, the expected preparation, and one link back to the system of record. For a customer onboarding call, include the account name and agenda. For an incident review, include the incident ID and document link. For an interview, include the role and interview stage.

Avoid putting secrets or private tokens in the event description. Calendar events can be forwarded, synced to mobile devices, copied into logs, or exposed to delegated assistants. If the meeting needs private context, link to an authenticated page instead of copying sensitive details into the invite.

If your workflow adds video meeting links, be clear about ownership. Some providers can create conference links automatically, while some teams prefer a static room, Zoom link, or physical location. Store the location value your script sent so support teams can debug missing video links without reading raw provider payloads.

## How do you handle updates and cancellations later?

Creating the invite is only the first state change. Store the event ID returned by the CLI so future jobs can update or cancel the same event. If the product only stores title, start time, and attendee list, it has no stable pointer back to the calendar object. That leads to duplicate events when someone reschedules.

Treat event updates as user-visible actions. Changing the start time, end time, location, or attendee list can send provider notifications. Your app should decide when to notify attendees and when to make a silent internal update. A calendar event is a communication channel, not just a database row.

For cancellations, keep a local cancellation reason. Providers can tell attendees that an event was canceled, but your app usually knows why: customer request, no-show, release rollback, support escalation, or duplicate booking. Storing the reason helps later reporting and gives support teams enough context to answer questions.

## What safety checks should run before sending invites?

Run an availability check before the create command, especially for meetings with more than one required attendee. Then validate the final start and end times, title, participant list, and organizer grant. A one-line script can create a real meeting, so it should fail loudly when required input is missing.

Use idempotency at the workflow level. If a CI job or background worker retries after a timeout, it should not create two meetings. Store a booking request ID and check whether an event was already created for that request before sending the command again. If an event exists, update it or return the existing record.

Log the command result without logging secrets. The event ID, organizer grant, title, and recipient domain are useful. API keys, private links, and full customer notes are not. Good logs let you trace whether a meeting was created while still keeping calendar data private.

## What should attendees expect after the invite is created?

Attendees expect the calendar provider to send a normal invite, not a custom email that only looks like one. A provider-created event can appear on the calendar, collect responses, and update when the organizer changes details. That makes the workflow feel native to the recipient instead of bolted onto email.

Set expectations in the product UI before creating the event. If the provider will notify attendees, say so. If the event is an internal hold that should not notify people, use a different workflow or verify that your command flags match that behavior. Users should not be surprised by calendar email.

For customer-facing flows, send a separate confirmation email only when it adds value. A calendar invite already lands in the inbox. A second email can be useful when it includes onboarding steps, payment details, or support instructions, but it should not repeat the same event data without purpose.

## Should CLI-created invites be recurring?

Use one-off events for most automation. Recurring events need more product decisions: recurrence pattern, end date, exceptions, skipped dates, attendee changes, and cancellation rules. If the workflow only books onboarding, interviews, release windows, or support calls, a single event is easier to reason about and easier to update.

When a recurring series is required, decide whether your system owns the full series or only creates the first event. A training program may need a six-week sequence. A support follow-up may need one meeting and a reminder task. Do not create recurrence because it seems convenient; create it because the user story requires a repeated calendar object.

Document how exceptions are handled. If a user moves the third meeting in a series directly in their calendar, your product needs to know whether that is allowed and how it syncs back. Without a clear rule, recurring events can drift away from the application's booking record.

## How should attendee responses feed back into the app?

A calendar invite can be accepted, declined, tentatively accepted, or ignored. If the application cares about attendance, register calendar webhooks and update your own booking state when responses change. Otherwise the app may keep showing a meeting as confirmed after the required attendee declined.

Decide which responses require action. A decline from an optional attendee might be fine. A decline from the customer, candidate, or organizer may need a reschedule flow. A tentative response might require a reminder. Turning provider responses into product states is part of owning the scheduling workflow.

Keep response handling idempotent. Providers can send multiple updates for the same event, and users can change their response. Store the latest response per attendee and compare it to prior state before triggering notifications or follow-up tasks. This avoids sending the same reschedule email several times.

## What is the quality bar for automated invites?

An automated invite should be as clear as a human-created invite. The title should name the purpose, the description should say what will happen, the location should be usable, and the attendee list should be intentional. Automation is not an excuse for vague calendar entries.

Test the exact invite in a real calendar before shipping. Create an event to a test account, inspect how it appears in Gmail and Outlook, accept it, decline it, move it, and cancel it. The command can create the event, but the user experience lives in the provider calendar and inbox.

Add monitoring around failed creates. If event creation fails because of auth, validation, provider limits, or missing attendees, users need a clear recovery path. A silent failure is worse than no automation because the user believes a meeting was booked when no invite exists.

## Where should invite text come from?

Invite text should come from a reviewed template or product-owned configuration, not from scattered shell strings. A script can still pass the final body to the CLI, but the wording should be easy to review, translate, and update. Meeting invites are user-facing messages.

Keep variables explicit. A template might accept account name, meeting purpose, preparation link, support contact, and booking ID. If a value is missing, fail before creating the event. A calendar invite with `undefined` in the description looks careless and can confuse attendees.

Version the template when the event drives an important workflow. If a customer asks what they received, support should know which text version was used. The event ID, booking ID, and template version together make the calendar object traceable.

Test templates with the same provider accounts your workflow uses. Different calendars and mail clients can present line breaks, links, and locations differently. A short live check catches formatting issues before customers receive the first automated invite.

Keep a plain-language fallback for operators. If event creation fails, the person handling the request should still know the proposed time, attendees, and purpose so they can book manually without reconstructing the request from logs.

Treat invite copy as part of the workflow contract. If the description promises a preparation link, agenda, or cancellation path, the product should provide those values before creating the event. A missing link is not just a copy issue; it can leave attendees without the information they need to join or prepare for the meeting.

## References for this workflow

- [Nylas Calendar and Events quickstart](https://developer.nylas.com/docs/v3/getting-started/calendar/) -- creating events through Nylas calendar APIs
- [RFC 5545 iCalendar](https://www.rfc-editor.org/rfc/rfc5545) -- the calendar object format behind ICS files
- [RFC 5546 iTIP](https://www.rfc-editor.org/rfc/rfc5546) -- scheduling messages for invites, replies, and cancellations

## Next steps

- [Check calendar availability from terminal](https://cli.nylas.com/guides/check-calendar-availability-cli) -- validate free time before sending invites
- [Calendly alternative for developers](https://cli.nylas.com/guides/calendly-alternative-developer-scheduling) -- build scheduling flows from calendar commands
- [Manage calendar events from terminal](https://cli.nylas.com/guides/manage-calendar-from-terminal) -- list, create, and schedule events
- [Command reference](https://cli.nylas.com/docs/commands) -- calendar events and availability flags