Skip to Content
POST
/api/v1/identities/{identityId}/pim/subscriptions/{publicId}

Subscribes the mailbox to a public collection and creates a read grant.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

identityId*string

Identity ULID identifier

publicId*string

Public directory listing ULID identifier

Response Body

Subscribed successfully

application/json
  1. response
category*|

Public category tag, or null

collectionId*string

Public collection ULID

components*array<>|

Supported primary components, in VEVENT then VTODO order; null for addressbooks. Legacy mixed calendars may also retain journals or unparsed resources. Narrowing refuses with components_conflict and a count of incompatible live and restorable trashed objects.

Items1 <= items <= 2
createdAt*integer

Creation timestamp in epoch seconds

Formatint64
description*|

Public description, or null

displayName*|

Public display name, or null

id*string

Directory entry id: the handle POST /subscriptions takes

kind*string

Collection type ('calendar' or 'addressbook')

Value in"calendar""addressbook"
ownerIdentityId*string

Identity ULID of the owner

Example Request
curl -X POST 'https://api.open.email/api/v1/identities/string/pim/subscriptions/string'
Example Response
{
  "category": "string",
  "collectionId": "string",
  "components": [
    "VEVENT"
  ],
  "createdAt": 0,
  "description": "string",
  "displayName": "string",
  "id": "string",
  "kind": "calendar",
  "ownerIdentityId": "string"
}