Team
Workspace members, roles (owner, admin, member, viewer) and invitations.
Look up an invitation
POST /v1/auth/invitation
For the accept page: workspace, role and whether the invited email already has an account.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
tokenrequired | string |
Responses
{
"workspace": {
"id": string,
"name": string
},
"email": string,
"role": string,
"roleLabel": string,
"invitedBy": {
"email": string,
"name": string or null
},
"expiresAt": string,
"accountExists": boolean,
"signedInAs": string or null,
"alreadyMember": boolean
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Accept an invitation
POST /v1/auth/invitation/accept
Signed in as the invited email: joins the workspace and switches this session to it. Not signed in and no account for the email: send password (and name) to create the account and join; this works whatever ONESEND_SIGNUP says, because the invitation is the permission. An account exists but you are not signed in: 401 login_required.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
tokenrequired | string | |
name | string | |
password | string | Only when creating a new account |
Responses
{
"token": string,
"user": {
"id": string,
"email": string,
"name": string or null
},
"workspace": {
"id": string,
"name": string,
"slug": string,
"plan": string
}
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
List workspace members
GET /v1/team/members
Every role can list members.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"userId": string,
"email": string,
"name": string or null,
"role": "viewer" | "member" | "admin" | "owner",
"joinedAt": string,
"twoFactorEnabled": boolean,
"you": boolean
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Change a member's role
PATCH /v1/team/members/{userId}
Admins and the owner. Roles: admin, member, viewer. The owner's role cannot be changed (transfer ownership instead), and nobody changes their own role.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
userIdrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
rolerequired | "admin" | "member" | "viewer" |
Responses
{
"userId": string,
"email": string,
"name": string or null,
"role": "viewer" | "member" | "admin" | "owner",
"joinedAt": string,
"twoFactorEnabled": boolean,
"you": boolean
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Remove a member
DELETE /v1/team/members/{userId}
Admins and the owner. The owner cannot be removed. Their sessions stop working in this workspace at once. To leave a workspace yourself, use POST /v1/team/leave.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
userIdrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Leave the current workspace
POST /v1/team/leave
Any role except the owner (transfer ownership first). You cannot leave your only workspace.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Transfer ownership to another member
POST /v1/team/transfer-ownership
Owner only, in a dashboard session. Confirm with your password (and two-factor code if it is on). You become an admin.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
userIdrequired | string | |
passwordrequired | string | Your current password, to confirm. |
code | string | Two-factor code, when two-factor authentication is on for your account. |
Responses
{
"data": [{
"userId": string,
"email": string,
"name": string or null,
"role": "viewer" | "member" | "admin" | "owner",
"joinedAt": string,
"twoFactorEnabled": boolean,
"you": boolean
}]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
List invitations
GET /v1/team/invitations
Admins and the owner. Pending invitations by default; status=all includes accepted, revoked and expired ones.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | "pending" | "all" |
Responses
{
"data": [{
"id": string,
"object": "invitation",
"email": string,
"role": "admin" | "member" | "viewer",
"status": "pending" | "accepted" | "revoked" | "expired",
"invitedBy": {
"email": string,
"name": string or null
},
"expiresAt": string,
"lastSentAt": string or null,
"sendCount": number,
"createdAt": string
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Invite someone by email
POST /v1/team/invitations
Admins and the owner. Sends an invitation email through this workspace's router (a system email). The link works for 7 days. Inviting an address that already has a pending invitation sends a new link and updates the role. When the email cannot be delivered (only the Sandbox), link returns the invitation link to a signed-in admin to pass on; never to an API key (an API key cannot invite someone without the email reaching them). An invitation sent with an API key is tied to it: when the key is revoked or reported as leaked (or a key that created it is), the invitation is canceled, and a member who joined through it is removed from the workspace (their API keys, inbox rules, forwarding and connected mailboxes stop too). Sending it again from the dashboard unties it.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) | |
role | "admin" | "member" | "viewer" | Default "member". |
Responses
{
"id": string,
"object": "invitation",
"email": string,
"role": "admin" | "member" | "viewer",
"status": "pending" | "accepted" | "revoked" | "expired",
"invitedBy": {
"email": string,
"name": string or null
},
"expiresAt": string,
"lastSentAt": string or null,
"sendCount": number,
"createdAt": string,
"emailDelivery": boolean,
"link": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Resend an invitation
POST /v1/team/invitations/{id}/resend
Sends a new link (the previous link stops working) and restarts the 7 days.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "invitation",
"email": string,
"role": "admin" | "member" | "viewer",
"status": "pending" | "accepted" | "revoked" | "expired",
"invitedBy": {
"email": string,
"name": string or null
},
"expiresAt": string,
"lastSentAt": string or null,
"sendCount": number,
"createdAt": string,
"emailDelivery": boolean,
"link": string
}Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Revoke an invitation
DELETE /v1/team/invitations/{id}
The link stops working at once.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
Errors: 400, 401, 403, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Team security settings
GET /v1/team/settings
Whether two-factor authentication is required, whether the workspace can deliver system email, and the role permission matrix.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"require2fa": boolean,
"emailDelivery": boolean,
"membersWithout2fa": number,
"roles": [{
"area": string,
"viewer": boolean,
"member": boolean,
"admin": boolean,
"owner": boolean
}]
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Require two-factor authentication
PATCH /v1/team/settings
Admins and the owner. With require2fa, members without two-factor authentication can only manage their own account until they turn it on and sign in again. Turn it on for your own account first.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
require2farequired | boolean |
Responses
{
"require2fa": boolean,
"emailDelivery": boolean,
"membersWithout2fa": number,
"roles": [{
"area": string,
"viewer": boolean,
"member": boolean,
"admin": boolean,
"owner": boolean
}]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)