--- title: "Your account" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/docs/api/reference/your-account" area: "API" category: "Reference" --- # Your account Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations The account of the person behind the key or the app: which email notifications they get, their profile photo and username, the apps they connected and the invitations waiting for them. These calls act on a person, never on a workspace: an API key acts for the workspace owner, and an app for the person who connected it. Reading needs `account:read` and every change needs `account:write`. Neither is ever limited by a role, so an app a member connected reaches the member's own account too. ### `GET /account/notifications` Read your notification settings Which kinds of email OpenEmail sends the person, as Account, Notifications shows them, and the workspaces whose notifications are muted on their phone. Account and billing email cannot be turned off. Requires the `account:read` scope. - Scopes: `account:read`. **Returns** - `200` `NotificationSettings`: The notification settings. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.getNotifications()`](https://openemail.uk/docs/sdk/reference/account#getNotifications); CLI [`openemail account get-notifications`](https://openemail.uk/docs/cli/reference/account#account-get-notifications); MCP [`getNotificationSettings`](https://openemail.uk/docs/mcp/tools/account#getNotificationSettings). ### `PUT /account/notifications/email/{category}` Turn a kind of email on or off `enabled: false` stops OpenEmail sending the person that kind of email, and `true` starts it again. `account` and `billing` cannot be turned off, and asking to is a 422 `invalid_parameter` on `category`. Requires the `account:write` scope. - Scopes: `account:write`. **Path parameters** - `category` (`string`, required, one of `"account"`, `"billing"`, `"activity"`, `"product"`): The kind of email. **Request body** - `enabled` (`boolean`, required): True to receive that email, false to stop it. **Returns** - `200` `NotificationSettings`: The notification settings as they are now. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.setEmailNotification()`](https://openemail.uk/docs/sdk/reference/account#setEmailNotification); CLI [`openemail account set-email-notification`](https://openemail.uk/docs/cli/reference/account#account-set-email-notification); MCP [`setEmailNotification`](https://openemail.uk/docs/mcp/tools/account#setEmailNotification). ### `PUT /account/notifications/push/{workspaceId}` Mute a workspace on your phone `muted: true` stops the phone app notifying the person about the mail of one workspace, and `false` lets it notify them again. It applies to every phone they signed in on. A workspace they cannot open is a 404. Requires the `account:write` scope. - Scopes: `account:write`. **Path parameters** - `workspaceId` (`string`, required): A workspace from `GET /workspaces`. **Request body** - `muted` (`boolean`, required): True to mute it, false to let it notify again. **Returns** - `200` `NotificationSettings`: The notification settings as they are now. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.setPushMuted()`](https://openemail.uk/docs/sdk/reference/account#setPushMuted); CLI [`openemail account set-push-muted`](https://openemail.uk/docs/cli/reference/account#account-set-push-muted); MCP [`setWorkspacePushMuted`](https://openemail.uk/docs/mcp/tools/account#setWorkspacePushMuted). ### `PUT /account/photo` Set your profile photo Uploads the person's profile photo, replacing any there was, as Account, Profile does. Send the image itself as the body, not JSON, with its type in `Content-Type`: `image/png`, `image/jpeg`, `image/webp`, `image/gif`. Up to 5 MB goes in. It is fitted into a 512 pixel square and stored as WebP, and an animated image keeps its first frame. Requires the `account:write` scope. - Scopes: `account:write`. **Request body** Content type: `image/png`, `image/jpeg`, `image/webp`, `image/gif`. `binary` **Returns** - `200` `AccountPhoto`: The photo, with its new `url`. **Errors** - `422`: `invalid_image` when the body is not an image of an accepted type, is too large or cannot be read. - `502`: `image_not_stored`: the image was read but could not be stored. Try again. - `503`: `image_busy`: the image service is saturated. Try again shortly. - The errors every operation can return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.setPhoto()`](https://openemail.uk/docs/sdk/reference/account#setPhoto); CLI [`openemail account set-photo`](https://openemail.uk/docs/cli/reference/account#account-set-photo); MCP [`setProfilePhoto`](https://openemail.uk/docs/mcp/tools/account#setProfilePhoto). ### `DELETE /account/photo` Remove your profile photo Removes the profile photo and deletes the stored image, so the app shows initials again. Removing it when there is none changes nothing. Requires the `account:write` scope. - Scopes: `account:write`. **Returns** - `200` `AccountPhoto`: Removed, with `url` null. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.removePhoto()`](https://openemail.uk/docs/sdk/reference/account#removePhoto); CLI [`openemail account remove-photo`](https://openemail.uk/docs/cli/reference/account#account-remove-photo); MCP [`removeProfilePhoto`](https://openemail.uk/docs/mcp/tools/account#removeProfilePhoto). ### `GET /account/username` Read your username The username of the person, whether they chose it or it was made for them, and the free address it gives them. A username is made from their name the first time it is read. Requires the `account:read` scope. - Scopes: `account:read`. **Returns** - `200` `Username`: The username. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.getUsername()`](https://openemail.uk/docs/sdk/reference/account#getUsername); CLI [`openemail account get-username`](https://openemail.uk/docs/cli/reference/account#account-get-username); MCP [`getUsername`](https://openemail.uk/docs/mcp/tools/account#getUsername). ### `PUT /account/username` Choose your username Sets the username for good, and with it the free address. Once chosen it never changes: a second choice is a 409 `username_locked`. A username another account has is a 409 `username_taken`, and one that is too short, too long, reserved or not lowercase letters, numbers and single dots is a 422 `invalid_parameter` on `username`. Check one first with `GET /account/username/availability`. Requires the `account:write` scope. - Scopes: `account:write`. **Request body** - `username` (`string`, required, up to 60 characters) **Returns** - `200` `Username`: The username, now chosen. **Errors** - `409`: `username_locked`: the username was chosen before and never changes. `username_taken`: another account has it. - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.setUsername()`](https://openemail.uk/docs/sdk/reference/account#setUsername); CLI [`openemail account set-username`](https://openemail.uk/docs/cli/reference/account#account-set-username); MCP [`chooseUsername`](https://openemail.uk/docs/mcp/tools/account#chooseUsername). ### `GET /account/username/availability` Check a username Whether the person could choose a username, without choosing it. The answer says why when they could not. Requires the `account:read` scope. - Scopes: `account:read`. **Query parameters** - `username` (`string`, required, 1 to 60 characters): The username to check. It is lowercased and its spaces become dots before it is checked, as the app does. **Returns** - `200` `UsernameAvailability`: The verdict. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.checkUsername()`](https://openemail.uk/docs/sdk/reference/account#checkUsername); CLI [`openemail account check-username`](https://openemail.uk/docs/cli/reference/account#account-check-username); MCP [`checkUsername`](https://openemail.uk/docs/mcp/tools/account#checkUsername). ### `GET /account/connected-apps` List your connected apps Every app the person connected with OAuth, as Account, Connected apps lists them: what each may reach, until when, how many tokens it holds and whether changes are allowed without a code for it right now. `current` marks the app making the call. Changing what an app may reach is done in the app, never through an app. Requires the `account:read` scope. - Scopes: `account:read`. **Returns** - `200` `ConnectedAppList`: The connected apps. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.listConnectedApps()`](https://openemail.uk/docs/sdk/reference/account#listConnectedApps); CLI [`openemail account list-connected-apps`](https://openemail.uk/docs/cli/reference/account#account-list-connected-apps); MCP [`listConnectedApps`](https://openemail.uk/docs/mcp/tools/account#listConnectedApps). ### `DELETE /account/connected-apps/{clientId}` Remove a connected app Deletes every token the app holds and the access the person gave it, so its next call is refused and it has to ask again. Removing the app making the call disconnects it. An app the person never connected is a 404. Requires the `account:write` scope. - Scopes: `account:write`. **Path parameters** - `clientId` (`string`, required): The app's `clientId` from `GET /account/connected-apps`. **Returns** - `200` `RevokedConnectedApp`: Removed. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.revokeConnectedApp()`](https://openemail.uk/docs/sdk/reference/account#revokeConnectedApp); CLI [`openemail account revoke-connected-app`](https://openemail.uk/docs/cli/reference/account#account-revoke-connected-app); MCP [`revokeConnectedApp`](https://openemail.uk/docs/mcp/tools/account#revokeConnectedApp). ### `GET /account/invitations` List your invitations The invitations to join a workspace waiting for the address the person signs in with, oldest first. Expired, accepted and withdrawn ones are left out. Requires the `account:read` scope. - Scopes: `account:read`. **Returns** - `200` `ReceivedInvitationList`: The invitations. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.listInvitations()`](https://openemail.uk/docs/sdk/reference/account#listInvitations); CLI [`openemail account list-invitations`](https://openemail.uk/docs/cli/reference/account#account-list-invitations); MCP [`listReceivedInvitations`](https://openemail.uk/docs/mcp/tools/account#listReceivedInvitations). ### `POST /account/invitations/{invitationId}/accept` Accept an invitation Joins the workspace with the role and the addresses the invitation gives, as accepting it in the app or from its link does. `activate: true` also makes it the workspace the app opens. A workspace that asks for two-factor sign-in is a 403 `two_factor_required` until the person turns it on, and an invitation that expired, was withdrawn or went to another address is a 422. Requires the `account:write` scope. - Scopes: `account:write`. **Path parameters** - `invitationId` (`string`, required): The invitation id from `GET /account/invitations`. **Request body** - `activate` (`boolean`) **Returns** - `200` `AcceptedInvitation`: Joined. **Errors** - `403`: `two_factor_required`: the workspace asks everyone in it to sign in with two-factor authentication. `mailbox_login`: a password sign-in for one address cannot join a workspace. - The errors every operation can return: `400`, `401`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.acceptInvitation()`](https://openemail.uk/docs/sdk/reference/account#acceptInvitation); CLI [`openemail account accept-invitation`](https://openemail.uk/docs/cli/reference/account#account-accept-invitation); MCP [`acceptInvitation`](https://openemail.uk/docs/mcp/tools/account#acceptInvitation). ### `POST /account/invitations/{invitationId}/decline` Decline an invitation Turns the invitation down, so its link stops working, and tells whoever sent it. It cannot be taken back: they have to invite the person again. An invitation they already accepted is a 409 `invitation_accepted`. Requires the `account:write` scope. - Scopes: `account:write`. **Path parameters** - `invitationId` (`string`, required): The invitation id from `GET /account/invitations`. **Returns** - `200` `DeclinedInvitation`: Declined. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`account.declineInvitation()`](https://openemail.uk/docs/sdk/reference/account#declineInvitation); CLI [`openemail account decline-invitation`](https://openemail.uk/docs/cli/reference/account#account-decline-invitation); MCP [`declineInvitation`](https://openemail.uk/docs/mcp/tools/account#declineInvitation). ### Objects #### `AcceptedInvitation` `object` - `object` (`string`, required, one of `"invitation"`) - `id` (`string`, required) - `accepted` (`boolean`, required, one of `true`) - `workspaceId` (`string`, required) - `workspaceName` (`string`, required) - `addressesGranted` (`integer`, required, at least 0) - `domainsGranted` (`integer`, required, at least 0) - `activated` (`boolean`, required): Whether the app now opens the workspace, after `activate: true`. #### `AccountPhoto` `object` - `object` (`string`, required, one of `"account_photo"`) - `url` (`string`, required, nullable) #### `ConnectedApp` `object` - `object` (`string`, required, one of `"connected_app"`) - `clientId` (`string`, required) - `name` (`string`, required, nullable) - `kind` (`string`, required, one of `"app"`, `"cli"`): `cli` for a sign-in of the command line tool, `app` for every other app. - `cliDevice` (`string`, nullable) - `current` (`boolean`, required): Whether it is the app making this call. - `registeredByAccount` (`boolean`) - `redirectUris` (`string[]`) - `connectedAt` (`string`, nullable, format `date-time`) - `accessUntil` (`string`, nullable, format `date-time`): When its last token runs out. - `tokenCount` (`integer`, required, at least 0) - `status` (`string`, required, one of `"active"`, `"expired"`, `"needs-approval"`, `"access-lost"`) - `usablePermissions` (`integer`, nullable): How many of the permissions it was given the person still holds. - `elevatedUntil` (`string`, nullable, format `date-time`): Until when it may make changes that ask for a verification code without one. - `grant` (`object`, nullable): What the person gave it, or null for an app that has to ask again. - `workspaceId` (`string`, required): The one workspace the app acts for. - `workspaceName` (`string`, required, nullable) - `permissions` (`string[]`, required) - `addressAllowlist` (`string[]`, required, nullable) - `domainAllowlist` (`string[]`, required, nullable) - `expiresAt` (`string`, required, nullable, format `date-time`): When the access ends, or null when it lasts until it is removed. - `updatedAt` (`string`, required, format `date-time`) #### `ConnectedAppList` `object` - `object` (`string`, one of `"list"`) - `data` (`ConnectedApp[]`) #### `DeclinedInvitation` `object` - `object` (`string`, required, one of `"invitation"`) - `id` (`string`, required) - `declined` (`boolean`, required, one of `true`) #### `EmailNotificationSetting` `object` - `category` (`string`, required, one of `"account"`, `"billing"`, `"activity"`, `"product"`) - `label` (`string`, required) - `description` (`string`, required) - `required` (`boolean`, required): Whether it can never be turned off. - `enabled` (`boolean`, required) #### `NotificationSettings` `object` - `object` (`string`, required, one of `"notification_settings"`) - `email` (`EmailNotificationSetting[]`, required): Every kind of email OpenEmail sends. - `mutedWorkspaces` (`string[]`, required): The workspaces whose notifications are muted on the phone. #### `ReceivedInvitation` `object` - `object` (`string`, required, one of `"invitation"`) - `id` (`string`, required) - `workspaceId` (`string`, required) - `workspaceName` (`string`, required) - `roleName` (`string`, required) - `inviterName` (`string`, nullable) - `addresses` (`integer`, required, at least 0): How many addresses and whole domains it gives. - `expiresAt` (`string`, required, format `date-time`) - `createdAt` (`string`, required, format `date-time`) #### `ReceivedInvitationList` `object` - `object` (`string`, one of `"list"`) - `data` (`ReceivedInvitation[]`) #### `RevokedConnectedApp` `object` - `object` (`string`, required, one of `"connected_app"`) - `clientId` (`string`, required) - `revoked` (`boolean`, required, one of `true`) - `tokensRevoked` (`integer`, required, at least 0) #### `Username` `object` - `object` (`string`, required, one of `"username"`) - `username` (`string`, required, nullable) - `chosen` (`boolean`, required): Whether the person chose it. A chosen username never changes. - `address` (`string`, required, nullable): The free address the username gives, when this deployment offers one. #### `UsernameAvailability` `object` - `object` (`string`, required, one of `"username_availability"`) - `username` (`string`, required): The username as it was checked. - `status` (`string`, required, one of `"available"`, `"current"`, `"taken"`, `"reserved"`, `"invalid"`, `"too_short"`, `"too_long"`): `current` when it is the username the person already has. - `available` (`boolean`, required) - `message` (`string`, required)