---
title: "Calendar subscriptions"
description: "Other calendars you subscribe to by link, whose events show on your calendar read-only."
url: "https://openemail.uk/docs/api/calendar/subscriptions"
area: "API"
category: "Mailbox"
---

# Calendar subscriptions

Other calendars you subscribe to by link, whose events show on your calendar read-only.

`POST /calendar/subscriptions`

**Also documents:** `GET /calendar/subscriptions`, `PATCH /calendar/subscriptions/{id}`, `POST /calendar/subscriptions/{id}/refresh`, `DELETE /calendar/subscriptions/{id}`

## POST /calendar/subscriptions

Other calendars you subscribe to by link, whose events show on your calendar read-only.

## Subscribe

Needs `calendar:write`. `url` is an `https`, `http` or `webcal` link to an iCalendar file, and `name` defaults to the name the calendar gives itself.

**curl**

```
curl -X POST "$OE/calendar/subscriptions" -H "$AUTH" -H 'content-type: application/json' -d '{ "url": "webcal://example.com/holidays.ics", "color": "green" }'
```

**Response**

```
{
  "object": "calendar_subscription",
  "id": "csb_8d3f0a2b9c4e41f7a6b5c2d1",
  "name": "Public holidays",
  "url": "https://example.com/holidays.ics",
  "color": "green",
  "status": "active",
  "lastError": null,
  "eventCount": 24,
  "lastSyncedAt": "2026-10-10T12:00:03.000Z",
  "lastFetchedAt": "2026-10-10T12:00:03.000Z",
  "createdAt": "2026-10-10T12:00:01.000Z"
}
```

> The calendar is read at once and then about every 30 minutes. `GET /calendar/subscriptions` lists them, `PATCH /calendar/subscriptions/{id}` renames one or changes its `color`, `POST /calendar/subscriptions/{id}/refresh` reads one again now, and `DELETE /calendar/subscriptions/{id}` removes it with its events.

> A link that does not answer with a calendar is a 422 `calendar_subscription_unreadable`, one you already subscribe to a 409 `calendar_subscription_exists`, and a refresh within a minute of the last read a 429 `calendar_subscription_refresh_too_soon`. `status` turns `failing` while reads fail and `stopped` after ten failures in a row, with the reason in `lastError`.

> Events from a subscription carry its `subscriptionId` and cannot be changed, which is a 403 `event_read_only`. A key limited to some addresses or domains is a 422 `capability_unsupported`.

## Reference

- [`POST /calendar/subscriptions`](https://openemail.uk/docs/api/reference/calendar#post-calendar-subscriptions): full reference
- [`GET /calendar/subscriptions`](https://openemail.uk/docs/api/reference/calendar#get-calendar-subscriptions): full reference
- [`PATCH /calendar/subscriptions/{id}`](https://openemail.uk/docs/api/reference/calendar#patch-calendar-subscriptions-id): full reference
- [`POST /calendar/subscriptions/{id}/refresh`](https://openemail.uk/docs/api/reference/calendar#post-calendar-subscriptions-id-refresh): full reference
- [`DELETE /calendar/subscriptions/{id}`](https://openemail.uk/docs/api/reference/calendar#delete-calendar-subscriptions-id): full reference