Docs / API reference

Auth

Dashboard accounts and session tokens.

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

Create an account

POST /v1/auth/signup

The first account on a fresh instance becomes the owner. Afterwards signup follows ONESEND_SIGNUP. Sets the onesend_session HttpOnly cookie for the dashboard and returns the session token for scripts.

Authentication: None.

Request body

application/json, required.

FieldTypeDescription
emailrequiredstring (email)
passwordrequiredstring
namestring
workspaceNamestring
setupCodestringThe setup code printed by the installer (ONESEND_SETUP_CODE). Needed only for the first account, when the server has one.

Responses

201 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)

Sign in

POST /v1/auth/login

Sets the onesend_session HttpOnly cookie for the dashboard and returns the session token for scripts. Rate limited per client and per account. Accounts with two-factor authentication get 401 mfa_required with error.details.mfaToken; finish with POST /v1/auth/login/2fa.

Authentication: None.

Request body

application/json, required.

FieldTypeDescription
emailrequiredstring (email)
passwordrequiredstring

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)

Sign out (revoke the session and clear the cookie)

POST /v1/auth/logout

Authentication: None.

Responses

204 No content

Errors: 400, 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.
  • 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)

Current user, workspace and credentials

GET /v1/auth/me

Authentication: Authorization: Bearer with an API key or a session token.

Responses

200 Success

{
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string,
    "settings": object
  },
  "workspaces": [{
    "id": string,
    "name": string,
    "role": string
  }],
  "auth": {
    "kind": "session" | "api_key",
    "scope": string,
    "mode": string
  },
  "role": string or null,
  "twoFactor": {
    "enabled": boolean,
    "required": boolean,
    "blocked": boolean
  },
  "capabilities": {
    "edition": "self_hosted" | "cloud" | "desktop",
    "inbox": boolean,
    "connectedAccounts": boolean,
    "encryptMail": boolean,
    "cloudLink": {
      "linked": boolean,
      "url": string,
      "workspaceName": string
    },
    "license": {
      "required": boolean,
      "active": boolean
    },
    "plansEnabled": 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)

Switch the current workspace

POST /v1/auth/workspace

Sessions only. Later requests with this session act in the chosen workspace (the dashboard workspace switcher). Scripts can also send X-Workspace-Id per request. API keys always belong to one workspace.

Authentication: Authorization: Bearer with an API key or a session token.

Request body

application/json, required.

FieldTypeDescription
workspaceIdrequiredstring

Responses

200 Success

{
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  },
  "role": 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)

Sign in: second step

POST /v1/auth/login/2fa

When the account has two-factor authentication, sign-in answers 401 mfa_required with error.details.mfaToken; send it here with the code from the authenticator app or a recovery code. The challenge is valid for 5 minutes.

Authentication: None.

Request body

application/json, required.

FieldTypeDescription
mfaTokenrequiredstring
codestring
recoveryCodestring

Responses

200 Success

{
  "token": string,
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  },
  "recoveryCodesRemaining": number
}
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)

Request a password reset link

POST /v1/auth/password/forgot

Always answers 202 with the same message and timing, whether or not the email has an account. The email is sent through the router of a workspace the account belongs to. If the server cannot deliver email (only the sandbox provider), an administrator can create a link on the server: npm run admin -- reset-password <email>.

Authentication: None.

Request body

application/json, required.

FieldTypeDescription
emailrequiredstring (email)

Responses

202 Success

{
  "ok": true,
  "message": 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)

Check a password reset link

POST /v1/auth/password/check

Tells the reset page whether the link can still be used (and whether a two-factor code will be needed). Does not use the link.

Authentication: None.

Request body

application/json, required.

FieldTypeDescription
tokenrequiredstring

Responses

200 Success

{
  "valid": boolean,
  "twoFactor": 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)

Set a new password with a reset link

POST /v1/auth/password/reset

The link works once, for 30 minutes, and stops working if the password changes in the meantime. Every session of the account is signed out. Accounts with two-factor authentication also need a code (or a recovery code). Does not sign in: sign in with the new password afterwards.

Authentication: None.

Request body

application/json, required.

FieldTypeDescription
tokenrequiredstring
passwordrequiredstring
codestringTwo-factor code or recovery code, when the account has two-factor authentication

Responses

200 Success

{
  "ok": true
}
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)

First-run status

GET /v1/setup/status

Whether this instance has an account yet, and how sign-up works. No authentication. The database kind is shown only until the first account exists; paths, hosts and secrets are never returned.

Authentication: None.

Responses

200 Success

{
  "hasUsers": boolean,
  "databaseKind": "sqlite" | "postgres" | "libsql" | "pglite" | "d1" | null,
  "dataDirIsDefault": boolean or null,
  "publicUrl": string,
  "signupMode": "open" | "first-user" | "invite" | "closed",
  "signupAllowed": boolean,
  "setupCodeRequired": boolean
}
Errors: 400, 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.
  • 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)