# List collections shared with mailbox

Returns calendar and addressbook collections shared with the mailbox by other users.

## `GET /api/v1/identities/{identityId}/pim/shared-with-me`

### Path parameters

- `identityId` (string, required) — Identity ULID identifier

### Responses

**200** — List of shared collections

`application/json` → object

- `shared` (PimSharedWithMe[], required)
  - `collectionId` (string, required) — Shared collection ULID
  - `color` (string | null, required) — Hex color code, or null
  - `components` (array | null, required, min 1 items, max 2 items) — 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.
  - `createdAt` (integer <int64>, required) — Timestamp when share was created in epoch seconds
  - `description` (string | null, required) — Collection description, or null
  - `descriptionLang` (string | null, required) — BCP 47 language tag (xml:lang) of the collection description, or null
  - `displayName` (string | null, required) — Display name, or null
  - `kind` ("calendar" | "addressbook", required) — Collection type ('calendar' or 'addressbook')
  - `name` (string, required) — URL slug name
  - `objectCount` (integer <int64>, required) — Total number of events, tasks, or contacts in this collection
  - `ownerAddress` (string | null, required) — Primary email address of the owner, or null for an address-less identity. The mirror of SharedMailbox.ownerAddress: a "shared with me" list names WHO shared
  - `ownerIdentityId` (string, required) — Identity ULID of the collection owner
  - `permission` ("read" | "read-write", required) — Access permission level
  - `scheduleTransp` ("opaque" | "transparent", required) — RFC 6638 §9.1 CALDAV:schedule-calendar-transp, as the OWNER set it — whether this calendar counts toward their free/busy
  - `syncToken` (string, required) — Current sync token
  - `taskCounts` (object, required) — Members that are tasks, split by the two `progress` buckets. Exact complements; events and contacts are in neither, so the pair need not sum to `objectCount`.
    - `active` (integer <int64>, required) — Tasks not completed or cancelled — what `?progress=active` lists
    - `closed` (integer <int64>, required) — Tasks completed or cancelled — what `?progress=closed` lists

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/identities/{identityId}/pim/shared-with-me' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.pim.listSharedWithMe`](/docs/sdks/typescript/pim/list-shared-with-me)

```ts
const result = await openemail.pim.listSharedWithMe(identityId)
```
