Docs / API reference

Team

Workspace members, roles (owner, admin, member, viewer) and invitations.

Base URL https://your-server.example (your OneSend server). Authentication and errors are described in the overview.

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

application/json, required.

FieldTypeDescription
tokenrequiredstring

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
tokenrequiredstring
namestring
passwordstringOnly when creating a new account

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
userIdrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
rolerequired"admin" | "member" | "viewer"

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
userIdrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
userIdrequiredstring
passwordrequiredstringYour current password, to confirm.
codestringTwo-factor code, when two-factor authentication is on for your account.

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
statusquery"pending" | "all"

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
emailrequiredstring (email)
role"admin" | "member" | "viewer"Default "member".

Responses

201 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

NameInTypeDescription
idrequiredpathstring

Responses

204 No content

Errors: 400, 401, 403, 404, 409, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

200 Success

{
  "require2fa": boolean,
  "emailDelivery": boolean,
  "membersWithout2fa": number,
  "roles": [{
    "area": string,
    "viewer": boolean,
    "member": boolean,
    "admin": boolean,
    "owner": boolean
  }]
}
Errors: 400, 401, 403, 404, 429, 500
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected 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

application/json, required.

FieldTypeDescription
require2farequiredboolean

Responses

200 Success

{
  "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
  • 400 Invalid 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). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), 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 missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)