---
title: "Calendar"
description: "The calendar is part of the inbox: every member has a personal calendar, the team can share calendars, events can repeat, and invitations go out by email from your own addresses, with answers coming back by email or from a link."
url: https://onesend.email/docs/calendar/
---
# Calendar

The calendar is part of the inbox: every member has a personal calendar, the team can share calendars, events can repeat, and invitations go out by email from your own addresses, with answers coming back by email or from a link. It is available wherever the inbox is (self-hosted servers and the Mac app; not the cloud edition, `ONESEND_INBOX=off` turns it off with the inbox: 403 `inbox_unavailable`, public pages 404).

In the dashboard: **Calendar** in the sidebar (day, week, month and agenda views; drag an event in the day or week view to move it, or its lower edge to change its end). In the Mac app: **Calendar** in the mail window's sidebar. Booking pages, where people outside the workspace pick a free time: see [Booking pages](https://onesend.email/docs/booking/).

All endpoints are under `/v1/calendar`. Reads need a Read only key or better, changes a Full access key or a member session; viewers can read, not change. Test-mode keys and apps (OAuth tokens, MCP) cannot use the calendar or booking API (403 `test_key_not_allowed`, `apps_cannot_use_calendar`): its changes send real invitations from your addresses.

## Calendars and who sees them

| `kind` | `access` | Who sees it and its events |
|---|---|---|
| `personal` | `personal` | Its owner only. Created for each member the first time they use the calendar. It cannot be shared or deleted. |
| `shared` | `workspace` (default) | Every member of the workspace. |
| `shared` | `members` | The members in `accessUserIds`, plus the workspace's owners and admins. |
| `shared` | `personal` | Only the member who made it. |

The rules are the mailbox rules ([Who can read a mailbox](https://onesend.email/docs/inbox/#who-can-read-a-mailbox)) with one difference: owners and admins do not see someone else's personal calendar at all. For everyone who may not see a calendar, the calendar and its events do not exist: **404** (never 403) on the calendar, its events, export, import and feed endpoints, and they are left out of every list, range, free/busy answer and the workspace export. API keys act for the member who created them, so no key reads another member's personal calendar; a key without a member reads `workspace` calendars only.

Changing a calendar itself (name, color, its feed, deleting it) needs its owner (personal) or, for a shared calendar, its creator or a workspace owner or admin. Who sees a shared calendar that is `workspace` or `members` (its `access` and `accessUserIds`) is changed by owners and admins only (403 `calendar_access_admin_only`), so whoever made it cannot hide it from colleagues; a shared calendar that is `personal` can be opened up by the member who made it. Everyone who sees a calendar can add and change its events. When a member leaves, they are taken off `members` lists and the subscription URLs they made (and that of their personal calendar) stop; their personal calendar stays closed. A workspace has at most 200 calendars.

| Method | Path | Purpose |
|---|---|---|
| GET, POST | `/calendar/calendars` | List (your personal calendar first), create a shared one: `{ "name": "Support rota", "access": "members", "accessUserIds": ["usr_…"], "color": "#16A34A", "timeZone": "Europe/Berlin" }`. |
| GET, PATCH, DELETE | `/calendar/calendars/{id}` | Read, change, delete (a shared calendar and its events; guests are not notified). |
| GET | `/calendar/calendars/{id}/export` | The calendar as an `.ics` file. |
| POST | `/calendar/calendars/{id}/import` | `{ "ics": "BEGIN:VCALENDAR…" }`, at most 1 MB. |
| POST, DELETE | `/calendar/calendars/{id}/feed` | Create (or replace) the private subscription URL; turn it off. |

## Events

```bash
curl -X POST http://localhost:3000/v1/calendar/events -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Standup","start":"2026-11-16T09:00","end":"2026-11-16T09:15","timeZone":"Europe/Berlin","rrule":"FREQ=WEEKLY;BYDAY=MO,WE,FR","reminders":[{"minutes":10,"method":"notification"}]}'
```

| Field | Meaning |
|---|---|
| `calendarId` | Default: your default calendar (Calendar settings), else your personal calendar. |
| `title`, `description`, `location`, `url` | At most 500, 10,000, 500 and 2,000 characters. `url` is an http or https link. |
| `start`, `end` | An ISO 8601 time with an offset (`2026-11-16T08:00:00Z`), or a local time (`2026-11-16T09:00`) read in `timeZone`. All-day events: dates, `end` the day after the last day (exclusive, as in iCalendar). At most 366 days long, between 1900 and 2200 (also for invitations from mail and imported files: others are not stored). |
| `timeZone` | An IANA zone such as `Europe/Berlin` (default: the calendar's, else UTC). Repeating events repeat at the same local time in it. |
| `allDay` | All-day events are floating dates: the same days in every zone. |
| `busy` | `busy` (default; all-day events: `free`) or `free`. Free events do not block booking slots or free/busy. |
| `color`, `status` | A hex color; `confirmed`, `tentative` or `cancelled`. |
| `rrule` | See [Repeating events](#repeating-events). |
| `attendees` | Up to 100 `{ "email", "name", "role": "required" \| "optional" }`. They are invited by email (see [Invitations](#invitations-by-email)). |
| `reminders` | Up to 5 of your own reminders: `{ "minutes": 0…40320, "method": "email" \| "notification" }`. |
| `sendFrom` | The mailbox or connected account (id) invitations are sent from: one of `GET /calendar/senders` (a mailbox you can read, not a catch-all, or a connected account whose mail you read), else 400 `invalid_send_from`. Default: Calendar settings (ignored when it is no longer one of yours). |
| `notify` | `false`: change the event without emailing attendees. |

| Method | Path | Purpose |
|---|---|---|
| GET | `/calendar/events?from=…&to=…&calendarIds=…&tz=…` | Occurrences in a range of at most 400 days, repeating events expanded, sorted by start. `tz` places all-day events. At most 5,000 occurrences (1,000 of one series); `truncated: true` says there were more. |
| POST | `/calendar/events` | Create. |
| GET, PATCH, DELETE | `/calendar/events/{id}` | Read, change, delete (with a scope for repeating events). |
| POST | `/calendar/events/{id}/rsvp` | Your answer as an attendee: `{ "partstat": "accepted" \| "tentative" \| "declined" }`. For an invitation added from an email, a METHOD:REPLY goes to its organizer. |
| GET | `/calendar/freebusy?from=…&to=…&calendarIds=…` | Busy intervals only (merged, no titles), of calendars you can read, at most 62 days. |

Each occurrence in a range has `id` (the event row: a series, a single event or a changed occurrence), `seriesId`, `recurrenceId` (the occurrence's original start, which identifies it), `recurring`, `exception`, its `start` and `end`, `attendees` (with `self` for you), your `reminders`, `organizer` and `source` (`local`, `invite`, `import`, `booking`).

### Repeating events

`rrule` takes the iCalendar RRULE subset: `FREQ` (`DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`), `INTERVAL`, `BYDAY` (`MO,WE`, and with a position for monthly and yearly rules: `2TU`, `-1FR`), `BYMONTHDAY` (negative counts from the end of the month: `-1` is the last day), `BYMONTH`, `COUNT` (up to 5,000) or `UNTIL`, and `WKST`. Anything else (`BYSETPOS`, `FREQ=HOURLY`, …) is refused with 400 `invalid_rrule`; imported events with such a rule keep their first occurrence only.

Expansion is bounded, also for the public booking pages that read the host's calendars: a series without `COUNT` starts at the period of the range (every `FREQ`), at most 20,000 candidate days are looked at per series and 300,000 per request (`truncated: true` past that), and it stops at the first period after the range. Expansion works on the event's local time, so a 09:00 meeting in `Europe/Berlin` is at 08:00 UTC in winter and 07:00 UTC in summer. A local time that does not exist on a given day (the hour clocks skip in spring) is read after the gap (02:30 becomes 03:30); one that occurs twice (the hour after clocks go back) is the first one, as RFC 5545 says. The first occurrence is always the event's start. `COUNT` counts occurrences that were later removed too.

Changing or deleting one occurrence takes a scope:

| `scope` | Change | Delete |
|---|---|---|
| `this` (with `occurrence`) | That occurrence gets its own row (`exception: true`): new times, title, place, guests. | The occurrence is removed (EXDATE). |
| `following` (with `occurrence`) | The series ends before this occurrence (`UNTIL`; `COUNT` is split) and a new series with a new UID starts here with the change. Later changed occurrences move to it when the time stayed the same. | The series ends before this occurrence. |
| `all` | The whole series. With `occurrence`, a new `start` and `end` move the series by the same amount (dragging one occurrence). When the time, zone or rule changes, changed occurrences and removed ones are dropped: they described other times. | The series and its changed occurrences. |

```bash
curl -X PATCH "http://localhost:3000/v1/calendar/events/evt_…" -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"scope":"this","occurrence":"2026-11-18T08:00:00.000Z","start":"2026-11-18T10:00","end":"2026-11-18T10:15"}'
curl -X DELETE "http://localhost:3000/v1/calendar/events/evt_…?scope=following&occurrence=2026-12-02T08:00:00.000Z" -H "Authorization: Bearer $ONESEND_API_KEY"
```

## Invitations by email

Events with attendees are sent as iMIP invitations (RFC 5546 over RFC 6047), so Apple Mail, Gmail, Outlook and other calendar apps show them as invitations:

- **Who sends.** The organizer is the person who adds attendees; the invitation comes from `sendFrom` (a mailbox you can read, through your routing and providers, or one of your connected accounts, through its own server), else from Calendar settings, else from a mailbox or account with your address, else your personal mailbox or your connected account. Without one: 400 `organizer_address_required` (or the invitation is not sent, when the address went away later). Replies from attendees come back to that address.
- **What is sent.** One message per attendee, with the event as a `text/calendar; method=REQUEST` part (`invite.ics`, with a VTIMEZONE for the event's zone) and Accept / Maybe / Decline links. A change to the time, title, place, description, link or status sends an update with `SEQUENCE` one higher (and asks attendees to answer again when the time changed); added attendees get the invitation; removed ones a `METHOD:CANCEL`; deleting sends `METHOD:CANCEL` to everyone (built before the event is gone). Changing one occurrence sends that occurrence (`RECURRENCE-ID`). Imported events and invitations you received never send anything.
- **How it runs.** Messages are sent by the `calendar_itip` job, one per attendee, within its query budget (Cloudflare D1: the invocation budget, as campaign jobs do); the rest continue in a new job. The content waits in the job encrypted (like system email bodies). The organizer must still be a member who can send (not a viewer). Each message is stored with its mailbox from the start, so mail of a personal mailbox never reaches workspace webhooks or chat.
- **API keys.** A change made with a key carries the key into the job: when it sends, the key must still be live and not revoked or expired, and its recipient allowlist, hourly and daily limits and sender domains apply as for any send (refused recipients are skipped). Keys follow the sending mailbox's [send policy](https://onesend.email/docs/inbox/): when it would hold their mail for approval (`approval`, or `allowlist` with an attendee outside it), the change is refused before it is made (403 `approval_required`), since an invitation cannot wait as a draft; send it from the dashboard, or pass `notify: false`. The same holds for answers (REPLY) sent with a key.

### Answers

- **From the links.** Each link carries a signed token (purpose `calendar_rsvp`, with the workspace, the event, the attendee's address and the occurrence) that expires a month after the event (a series: a year and a month; at most 400 days). It opens `/calendar/rsvp`, a page with the event and the three answers as buttons; only pressing one records it (a POST), so link scanners answer nothing. A token works only for its attendee on its event: a removed attendee, a deleted event, a changed signature or another purpose make it invalid (404 page). Rate limited per client address.
- **By email.** Received mail with a `METHOD:REPLY` calendar part updates the attendee who answered, when the event was organized here, the reply's ATTENDEE is the message's own From address, authentication passed for that address's domain (DMARC, or SPF or DKIM aligned with From: a pass for the sender's own envelope domain does not count), it was sent to the organizer's address and arrived in the event's sending mailbox (or one its organizer reads), and its `SEQUENCE` is the event's current one (an answer to an older time does not count). Anything else is ignored (a reply naming someone else does nothing).
- **In OneSend.** `POST /calendar/events/{id}/rsvp`, or the buttons on the event.

### Invitations you receive

A received message with a calendar part (a `text/calendar` part or an `.ics` file) shows an invitation card in the reader (web and Mac app): the event, its organizer, and **Accept**, **Maybe** and **Decline**.

- **An event organized in this workspace** (the same UID and organizer, in a calendar you can read): answering only sets your own answer on it, as `POST /calendar/events/{id}/rsvp` does. Nothing else of it changes (not its time, calendar, free/busy or the others' answers), nothing is copied, and no REPLY is mailed: the organizer sees your answer. `existing.organizedHere` is true.
- **Otherwise** answering adds the event to your default calendar (or updates your own copy, `source: invite`, one you added) with your answer, and sends METHOD:REPLY to the organizer from the address that received the invitation (its mailbox, or connected account). A declined invitation stays in your calendar as free time. Copies of others and events organized here are never overwritten, moved or marked free; an invitation with the UID of your copy from another organizer is refused (409 `uid_conflict`). At most 20 changed occurrences are added with a copy.

Later mail from the organizer updates the copies: a higher `SEQUENCE` changes its time and details (your answer stays), the same `SEQUENCE` only refreshes the other attendees' answers, a lower one or one more than 1,000 higher is ignored; `METHOD:CANCEL` (not lower) marks it canceled (or removes one occurrence), and the card offers **Remove from calendar**. Only mail from the event's organizer address with authentication aligned with its domain changes a copy, and only copies added from the mailbox that received it or by someone who can read that mailbox; Spam changes nothing. One message changes at most 20 events, 5 copies each, and writes attendees in a few statements (on D1 a message stays far below the 1,000 per invocation).

| Method | Path | Purpose |
|---|---|---|
| GET | `/calendar/invitations/{messageId}` | The card: `method`, `state` (`new`, `current`, `outdated`, `canceled`, `reply`), the event, `me` (your attendee address and answer), `existing` (your copy). 404 when you may not read the message or it has no calendar part. |
| POST | `/calendar/invitations/{messageId}/respond` | `{ "partstat": "accepted", "calendarId": "cal_…", "notify": true }`. |
| POST | `/calendar/invitations/{messageId}/remove` | A canceled invitation: remove your copy. |

## Reminders

Reminders are per person: each member sets their own on any event they can see. `email` sends a system email to the member's address; `notification` is shown by the Mac app as a native notification (it asks `GET /calendar/notifications?since=…` every minute and when the Mac wakes; **Settings → Notifications** decides whether it shows them). Reminders of all-day events count from midnight in the member's time zone.

The `calendar_tick` job runs every minute: it takes the due reminders in order of their time (`next_trigger_at`, indexed), claims each with a conditional update so it fires once even with several workers, sends it, and moves it to the next occurrence. At most 50 per run, within the D1 query budget; it continues at once when more are due. A reminder more than an hour late (the server was off) is skipped. A member who can no longer read the calendar gets no reminder.

## ICS files and the subscription URL

- **Export** writes every event of the calendar (at most 5,000 series and single events, with their changed occurrences and attendees) as iCalendar.
- **Import** reads an `.ics` file of at most 1 MB: events, repeat rules, removed occurrences (EXDATE), changed occurrences (RECURRENCE-ID), attendees and organizers; time zones by IANA name (also inside ids such as `/mozilla.org/…/Europe/Berlin`) or common Windows names, else the calendar's zone. An event whose UID is already in the calendar is updated unless the file's `SEQUENCE` is older. Nothing is sent to attendees. The first 100 events are written in the request; the rest by `calendar_import` jobs (encrypted, 100 each, within their query budget). Reading is bounded: at most 100,000 lines, 5,000 events, components nested 6 deep (deeper ones are skipped), 20,000 characters per value; nothing is fetched from the network.
- **Subscription URL**: `/calendar/feed/{token}.ics`, read-only, for Apple Calendar, Google Calendar or Outlook. The token is random (32 bytes) and only its sha256 is stored, so the URL is shown once. Creating it again replaces it; turning it off removes it; either stops the old URL at once. It holds the events that end after 400 days ago. Only whoever manages the calendar can create it, and it works while they can read the calendar (`feed_created_by`, 0047; checked whenever it is read): it stops when they leave the workspace or lose access. Served with `Cache-Control: private, max-age=300`, not indexed, rate limited per client address.

The pages without sign-in (answer links, subscription URLs, booking pages) answer 404 for a workspace being deleted or suspended, like any link that is not valid.

## Settings

`GET/PATCH /calendar/settings`: `timeZone` (the views show times in it; default the browser's), `weekStart` (0 Sunday … 6 Saturday), `defaultCalendarId`, `workingHours` (`{ "mon": [["09:00", "17:00"]], … }`, at most 6 ranges a day) and `sendFrom` (one of `GET /calendar/senders`: your readable mailboxes and connected accounts).

## Data and privacy

Tables (migrations 0044, 0047): `calendars`, `calendar_events`, `calendar_attendees`, `calendar_reminders`, `calendar_settings`. Every row has `workspace_id`, so workspace deletion purges them. The workspace data export includes calendars and shared calendars' events, and leaves out events, attendees and reminders of personal calendars (`calendar_id`, like personal mail; apps/server services/gdpr/registry.ts `PERSONAL_CALENDAR`). The feed token's hash is never exported. A contact's export (`GET /v1/contacts/{id}/export`) includes the bookings they made and their invitations (`calendar_attendees`), except those in personal calendars; erasing the contact anonymizes their bookings (name, address, answers and client address hash) and removes the address from every event's attendees.

Range reads use the index on (`calendar_id`, `start_at`, `range_end_at`): a series stores where it ends (`range_end_at`; year 9999 for series without an end), so a range is one indexed query plus one for changed occurrences. iMIP matching uses (`workspace_id`, `uid`).
