Skip to content
Docs
or

How to create Microsoft calendar events

Creating events on Microsoft 365 and Outlook calendars through Microsoft Graph means registering an Azure AD app, managing MSAL tokens, passing Windows timezone IDs in request bodies, and configuring admin consent for write access. If you want to support multiple calendar providers, you also need to build and maintain separate integrations for each one.

Nylas handles all of that behind a single REST API. You send the same create event request whether the account is Microsoft, Google, or iCloud. Nylas takes care of authentication, timezone conversion, and provider-specific formatting. This guide walks through creating events on Microsoft accounts, including participants, conferencing, recurring events, and the write-specific details you need to know.

Why use Nylas instead of Microsoft Graph directly?

Section titled “Why use Nylas instead of Microsoft Graph directly?”

Writing to Microsoft calendars through Graph is more involved than reading. You need Calendars.ReadWrite permissions, which are more likely to require admin consent in enterprise tenants. Request bodies need Windows timezone IDs. Attaching a Teams meeting requires a specific conferencing object structure. Notification behavior differs depending on how you configure the request, and error messages from Graph can be opaque when something goes wrong.

Nylas simplifies all of this. You pass IANA timezones (like America/New_York), and Nylas converts them for Microsoft. Conferencing auto-creation works through a single autocreate object. Participant notifications are controlled with one query parameter. Your create event code works identically across providers.

That said, if you only target Microsoft accounts and already have a working Graph integration, there’s no need to switch.

Before you begin

Section titled “Before you begin”

You’ll need:

  • A Nylas application with a valid API key
  • A grant for a Microsoft 365 or Outlook account
  • The Calendars.ReadWrite scope enabled in your Azure AD app registration (note: creating events requires the write scope, not just Calendars.Read)

New to Nylas? Start with the quickstart guide to set up your app and connect a test account before continuing here.

Section titled “Microsoft admin consent”

Microsoft organizations often require admin approval before third-party apps can access calendar data. Write scopes like Calendars.ReadWrite are more likely to trigger this requirement than read-only scopes. If your users see a “Need admin approval” screen during auth, their organization restricts user consent.

You have two options:

  • Ask the tenant admin to grant consent for your app via the Azure portal
  • Configure your Azure app to request only permissions that don’t need admin consent

Nylas has a detailed walkthrough: Configuring Microsoft admin approval. If you’re targeting enterprise customers, you’ll almost certainly need to deal with this.

You also need to be a verified publisher. Microsoft requires publisher verification since November 2020, and without it users see an error during auth.

Create an event

Section titled “Create an event”

You’re about to send a real event invite! The following samples send an email from the account you connected to the Nylas API to any email addresses you put in the participants sub-object. Make sure you actually want to send this invite to those addresses before running this command!

Make a Create Event request with the grant ID and a calendar_id query parameter. You can use primary as the calendar_id to target the account’s default calendar.

The calendar_id query parameter is required. For Microsoft accounts, calendar IDs are long base64-encoded strings, but primary works as a shortcut to target the default calendar. Nylas returns the created event with its id, which you can use for subsequent updates or deletions.

Add participants and send invitations

Section titled “Add participants and send invitations”

The notify_participants query parameter controls whether Microsoft sends email invitations to everyone in the participants array. It defaults to true, so participants receive calendar invitations automatically unless you explicitly disable it.

When notify_participants is set to false, the event is created only on the organizer’s calendar. Participants don’t receive an email, an ICS file, or any notification. The event won’t appear on their calendars at all.

Here’s an example with notifications explicitly enabled:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=primary&notify_participants=true' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Project kickoff",
    "when": {
      "start_time": 1674604800,
      "end_time": 1674608400,
      "start_timezone": "America/New_York",
      "end_timezone": "America/New_York"
    },
    "participants": [
      {
        "name": "Jordan Lee",
        "email": "[email protected]"
      }
    ]
  }'

Keep in mind: When notify_participants=false, your request doesn’t create an event for the participant. Participants don’t receive a message or an ICS file.

Things to know about Microsoft

Section titled “Things to know about Microsoft”

A few provider-specific details that matter when you’re creating events on Microsoft calendar accounts.

Section titled “Write scopes require admin consent more often”

The Calendars.ReadWrite scope is more likely to need admin approval than Calendars.Read, especially in enterprise tenants with strict consent policies. If your app previously worked with read-only access but fails on event creation, this is probably why. Check that the grant has the write scope and that the tenant admin has approved it.

Teams conferencing

Section titled “Teams conferencing”

You can automatically create a Microsoft Teams meeting when creating an event by using the conferencing object with autocreate. Nylas provisions the Teams link and attaches the join URL and dial-in details to the event. You can also manually add a Teams link by passing a conferencing object with provider set to "Microsoft Teams" and the meeting URL in details.

For the full setup, including configuring connectors for auto-creation, see Adding conferencing to events. You need an active Microsoft 365 subscription for Teams conferencing to work.

Timezones in request bodies

Section titled “Timezones in request bodies”

Nylas accepts IANA timezone identifiers in start_timezone and end_timezone (like America/New_York or Europe/London). You don’t need to convert to Windows timezone IDs the way you would with Microsoft Graph directly. Nylas handles the conversion before sending the request to Microsoft.

If you omit the timezone fields, Nylas uses the account’s default timezone.

All-day events

Section titled “All-day events”

To create an all-day event, use a datespan type with start_date and end_date as date strings (formatted YYYY-MM-DD). The end date is exclusive, meaning a single-day event on December 1st should have start_date: "2024-12-01" and end_date: "2024-12-02". This matches how Microsoft Graph represents all-day events internally and is consistent across providers.

"when": {
  "start_date": "2024-12-01",
  "end_date": "2024-12-02"
}

Room resources

Section titled “Room resources”

Microsoft supports booking conference rooms and other resources when creating events. Pass the room’s email address in the resources array:

"resources": [{
  "name": "Board Room 3A",
  "email": "[email protected]"
}]

The room must be accessible to the organizer’s account. If the room has an approval workflow or is restricted to certain groups, the booking may be declined. Check your organization’s room mailbox settings if bookings aren’t going through.

Recurring events

Section titled “Recurring events”

You can create recurring events by including a recurrence array with RRULE strings. Microsoft has a few limitations worth knowing:

  • Overrides are removed on recurrence change. If you modify a recurring series pattern (for example, changing from weekly to daily), Microsoft removes all existing overrides. Google keeps them if they still fit the pattern.
  • No multi-day monthly BYDAY. You can’t create a monthly recurring event on multiple days of the week (like the first and third Thursday). Microsoft’s recurrence model doesn’t support different indices within a single rule.
  • EXDATE recovery isn’t possible. Once you remove an occurrence from a recurring series, you can’t undo it through Nylas. You’d need to create a separate standalone event to fill the gap.

For the full breakdown of recurring event behavior and provider differences, see Recurring events.

Rate limits

Section titled “Rate limits”

Write operations count toward Microsoft’s per-mailbox rate limits, and create requests are heavier than reads. If your app triggers a 429 response, Nylas handles the retry automatically with appropriate backoff.

If you’re creating events in bulk (for example, migrating a calendar), space out requests to avoid hitting limits. For real-time awareness of event changes after creation, use webhooks instead of polling.

What’s next

Section titled “What’s next”