@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 parametersparseICS()-- parse iCalendar content into structured event datatoEmailAttachment()-- convert ICS content to an email-ready attachment objectCalendarError-- 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:
- Generates RFC 5545-compliant iCalendar (
.ics) content - Converts the ICS content into a MIME attachment using
@bernierllc/email-attachments - 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.