@bernierllc/email-calendar

iCalendar (RFC 5545) generation and parsing for email calendar invites and responses. Generates .ics files and converts them to email attachments compatible with all email providers.

Installation

npm install @bernierllc/email-calendar

Usage

import { generateICS, parseICS, toEmailAttachment } from '@bernierllc/email-calendar';

// Generate a calendar invite
const ics = generateICS({
  summary: 'Team Standup',
  start: new Date('2026-03-01T09:00:00Z'),
  end: new Date('2026-03-01T09:30:00Z'),
  organizer: { name: 'Jane', email: '[email protected]' },
  attendees: [
    { name: 'Bob', email: '[email protected]' },
  ],
  location: 'Conference Room A',
});

// Convert to an email attachment
const attachment = toEmailAttachment(ics, {
  filename: 'invite.ics',
  method: 'REQUEST',
});

// Parse an incoming ICS file
const event = parseICS(icsString);
console.log(event.summary, event.start, event.end);

Exports

• generateICS() -- create iCalendar content from event parameters
• parseICS() -- parse iCalendar content into structured event data
• toEmailAttachment() -- convert ICS content to an email-ready attachment object
• CalendarError -- custom error class with error codes
• Types: CalendarEvent, CalendarAttendee, CalendarOrganizer, ICSGenerateOptions, ICSParseResult, and more

Provider Capability Support

This section documents how calendar invites behave across email providers, based on the canonical CAPABILITY_MATRIX in @bernierllc/email-manager.

Capability Levels by Provider

| Provider | calendarInvites | calendarEventMgmt | Notes | |----------|------------------|---------------------|-------| | SendGrid | platform | platform | ICS attached to SendGrid emails | | Mailgun | platform | platform | ICS attached to Mailgun emails | | Postmark | platform | platform | ICS attached to Postmark emails | | SES | platform | platform | ICS attached to SES emails | | SMTP | platform | platform | ICS attached to SMTP emails |

How It Works

Calendar invites are implemented entirely at the platform level for all providers. This package:

1. Generates RFC 5545-compliant iCalendar (.ics) content
2. Converts the ICS content into a MIME attachment using @bernierllc/email-attachments
3. The attachment is then sent as part of a regular email through any provider

No provider has a native calendar invite API. The ICS file format is a universal standard that email clients (Outlook, Gmail, Apple Mail, Thunderbird, etc.) recognize and process natively, regardless of which email provider sent the message.

Degradation Behavior

There is no degradation. Calendar invites work identically across all providers because the feature is entirely provider-independent. The ICS file is a standard email attachment -- any provider that can send attachments (all of them) supports calendar invites.

No Override Needed

Since this feature operates at the platform level for all providers and produces a universal file format, there are no provider-specific behaviors to override. The output is always a standards-compliant .ics file attached to the email.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This package is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.