پرش به مستندات
API

حساب شما

هر عملیات در این گروه: آنچه می‌پذیرد، آنچه برمی‌گرداند و خطاهایی که ممکن است با آن‌ها پاسخ دهد.

عملیات‌ها

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

محدوده‌های دسترسیaccount:readمی‌خواند

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.

خروجی

The notification settings.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.getNotifications()
CLI
openemail account get-notifications
MCP
getNotificationSettings

PUT/account/notifications/email/{category}

Turn a kind of email on or off

محدوده‌های دسترسیaccount:writeداده‌ها را تغییر می‌دهد

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.

پارامترهای مسیر

categorystringالزامی

The kind of email.

یکی از"account""billing""activity""product"

بدنهٔ درخواست

enabledbooleanالزامی

True to receive that email, false to stop it.

خروجی

The notification settings as they are now.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.setEmailNotification()
CLI
openemail account set-email-notification
MCP
setEmailNotification

PUT/account/notifications/push/{workspaceId}

Mute a workspace on your phone

محدوده‌های دسترسیaccount:writeداده‌ها را تغییر می‌دهد

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.

پارامترهای مسیر

workspaceIdstringالزامی

A workspace from GET /workspaces.

بدنهٔ درخواست

mutedbooleanالزامی

True to mute it, false to let it notify again.

خروجی

The notification settings as they are now.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.setPushMuted()
CLI
openemail account set-push-muted
MCP
setWorkspacePushMuted

PUT/account/photo

Set your profile photo

محدوده‌های دسترسیaccount:writeداده‌ها را تغییر می‌دهد

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.

بدنهٔ درخواست

نوع محتواimage/png, image/jpeg, image/webp, image/gif

binary

خروجی

The photo, with its new url.

خطاها

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.

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404500فهرست خطاها

همچنین در دسترس در

SDK
account.setPhoto()
CLI
openemail account set-photo
MCP
setProfilePhoto

DELETE/account/photo

Remove your profile photo

محدوده‌های دسترسیaccount:writeحذف می‌کند

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.

خروجی

Removed, with url null.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.removePhoto()
CLI
openemail account remove-photo
MCP
removeProfilePhoto

GET/account/username

Read your username

محدوده‌های دسترسیaccount:readمی‌خواند

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.

خروجی

The username.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.getUsername()
CLI
openemail account get-username
MCP
getUsername

PUT/account/username

Choose your username

محدوده‌های دسترسیaccount:writeداده‌ها را تغییر می‌دهد

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.

بدنهٔ درخواست

usernamestringالزامی
تا 60 نویسه

خروجی

The username, now chosen.

خطاها

409

username_locked: the username was chosen before and never changes. username_taken: another account has it.

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.setUsername()
CLI
openemail account set-username
MCP
chooseUsername

GET/account/username/availability

Check a username

محدوده‌های دسترسیaccount:readمی‌خواند

Whether the person could choose a username, without choosing it. The answer says why when they could not.

Requires the account:read scope.

پارامترهای کوئری

usernamestringالزامی

The username to check. It is lowercased and its spaces become dots before it is checked, as the app does.

1 تا 60 نویسه

خروجی

The verdict.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.checkUsername()
CLI
openemail account check-username
MCP
checkUsername

GET/account/connected-apps

List your connected apps

محدوده‌های دسترسیaccount:readمی‌خواند

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.

خروجی

The connected apps.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.listConnectedApps()
CLI
openemail account list-connected-apps
MCP
listConnectedApps

DELETE/account/connected-apps/{clientId}

Remove a connected app

محدوده‌های دسترسیaccount:writeحذف می‌کند

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.

پارامترهای مسیر

clientIdstringالزامی

The app's clientId from GET /account/connected-apps.

خروجی

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.revokeConnectedApp()
CLI
openemail account revoke-connected-app
MCP
revokeConnectedApp

GET/account/invitations

List your invitations

محدوده‌های دسترسیaccount:readمی‌خواند

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.

خروجی

The invitations.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.listInvitations()
CLI
openemail account list-invitations
MCP
listReceivedInvitations

POST/account/invitations/{invitationId}/accept

Accept an invitation

محدوده‌های دسترسیaccount:writeداده‌ها را تغییر می‌دهد

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.

پارامترهای مسیر

invitationIdstringالزامی

The invitation id from GET /account/invitations.

بدنهٔ درخواست

activateboolean

خروجی

خطاها

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.

خطاهایی که هر عملیاتی ممکن است برگرداند400401404422500فهرست خطاها

همچنین در دسترس در

SDK
account.acceptInvitation()
CLI
openemail account accept-invitation
MCP
acceptInvitation

POST/account/invitations/{invitationId}/decline

Decline an invitation

محدوده‌های دسترسیaccount:writeحذف می‌کند

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.

پارامترهای مسیر

invitationIdstringالزامی

The invitation id from GET /account/invitations.

خروجی

Declined.

خطاها

خطاهایی که هر عملیاتی ممکن است برگرداند400401403404422500فهرست خطاها

همچنین در دسترس در

SDK
account.declineInvitation()
CLI
openemail account decline-invitation
MCP
declineInvitation

اشیا

AcceptedInvitationobject

objectstringالزامی
یکی از"invitation"
idstringالزامی
acceptedbooleanالزامی
یکی ازtrue
workspaceIdstringالزامی
workspaceNamestringالزامی
addressesGrantedintegerالزامی
دست‌کم 0
domainsGrantedintegerالزامی
دست‌کم 0
activatedbooleanالزامی

Whether the app now opens the workspace, after activate: true.

AccountPhotoobject

objectstringالزامی
یکی از"account_photo"
urlstringالزامی
می‌تواند null باشد

ConnectedAppobject

objectstringالزامی
یکی از"connected_app"
clientIdstringالزامی
namestringالزامی
می‌تواند null باشد
kindstringالزامی

cli for a sign-in of the command line tool, app for every other app.

یکی از"app""cli"
cliDevicestring
می‌تواند null باشد
currentbooleanالزامی

Whether it is the app making this call.

registeredByAccountboolean
redirectUrisstring[]
connectedAtstring
می‌تواند null باشدقالبdate-time
accessUntilstring

When its last token runs out.

می‌تواند null باشدقالبdate-time
tokenCountintegerالزامی
دست‌کم 0
statusstringالزامی
یکی از"active""expired""needs-approval""access-lost"
usablePermissionsinteger

How many of the permissions it was given the person still holds.

می‌تواند null باشد
elevatedUntilstring

Until when it may make changes that ask for a verification code without one.

می‌تواند null باشدقالبdate-time
grantobject

What the person gave it, or null for an app that has to ask again.

می‌تواند null باشد
workspaceIdstringالزامی

The one workspace the app acts for.

workspaceNamestringالزامی
می‌تواند null باشد
permissionsstring[]الزامی
addressAllowliststring[]الزامی
می‌تواند null باشد
domainAllowliststring[]الزامی
می‌تواند null باشد
expiresAtstringالزامی

When the access ends, or null when it lasts until it is removed.

می‌تواند null باشدقالبdate-time
updatedAtstringالزامی
قالبdate-time

DeclinedInvitationobject

objectstringالزامی
یکی از"invitation"
idstringالزامی
declinedbooleanالزامی
یکی ازtrue

EmailNotificationSettingobject

categorystringالزامی
یکی از"account""billing""activity""product"
labelstringالزامی
descriptionstringالزامی
requiredbooleanالزامی

Whether it can never be turned off.

enabledbooleanالزامی

NotificationSettingsobject

objectstringالزامی
یکی از"notification_settings"
emailEmailNotificationSetting[]الزامی

Every kind of email OpenEmail sends.

mutedWorkspacesstring[]الزامی

The workspaces whose notifications are muted on the phone.

ReceivedInvitationobject

objectstringالزامی
یکی از"invitation"
idstringالزامی
workspaceIdstringالزامی
workspaceNamestringالزامی
roleNamestringالزامی
inviterNamestring
می‌تواند null باشد
addressesintegerالزامی

How many addresses and whole domains it gives.

دست‌کم 0
expiresAtstringالزامی
قالبdate-time
createdAtstringالزامی
قالبdate-time

RevokedConnectedAppobject

objectstringالزامی
یکی از"connected_app"
clientIdstringالزامی
revokedbooleanالزامی
یکی ازtrue
tokensRevokedintegerالزامی
دست‌کم 0

Usernameobject

objectstringالزامی
یکی از"username"
usernamestringالزامی
می‌تواند null باشد
chosenbooleanالزامی

Whether the person chose it. A chosen username never changes.

addressstringالزامی

The free address the username gives, when this deployment offers one.

می‌تواند null باشد

UsernameAvailabilityobject

objectstringالزامی
یکی از"username_availability"
usernamestringالزامی

The username as it was checked.

statusstringالزامی

current when it is the username the person already has.

یکی از"available""current""taken""reserved""invalid""too_short""too_long"
availablebooleanالزامی
messagestringالزامی