Docs / API reference

Workspace

Workspace name and settings, such as tracking defaults and the attribution window.

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

Workspace settings (tracking, sandbox, brand) and SMTP details

GET /v1/workspace

While Sandbox mode is on, sandboxPending counts the scheduled campaigns and automation runs in progress that will send for real once it is off.

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

Responses

200 Success

{
  "id": string,
  "name": string,
  "slug": string,
  "plan": string,
  "settings": object,
  "smtp": {
    "host": string,
    "port": number or null,
    "username": string
  },
  "inbound": {
    "smtpPort": number or null,
    "cloudflareIngestUrl": string
  },
  "sandboxPending": {
    "scheduledCampaigns": integer,
    "activeAutomationRuns": integer
  }
}
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)

Update workspace settings

PATCH /v1/workspace

Turning Sandbox mode off (settings.sandbox: false) needs a signed-in admin. The response that turns it off has sandboxPending: the scheduled campaigns and automation runs in progress, started while it was on, that now send for real.

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

Request body

application/json, required.

FieldTypeDescription
namestring
settingsobject
settings.trackOpensboolean
settings.trackClicksboolean
settings.trackingDomainstring or null
settings.defaultPolicyIdstring or nullRouting policy for sends without policy. null or "" clears it.
settings.sandboxboolean
settings.campaignDailyCapinteger or nullMost campaign emails per day for one campaign, on top of provider limits. null: only provider limits. 1 to 100000000.
settings.timezonestring
settings.attributionWindowDaysinteger1 to 90.
settings.companyAddressstring or null
settings.brandobject
settings.brand.logoUrlstring
settings.brand.primarystring
settings.brand.accentstring
settings.brand.fontstring
settings.themesarray of objectSaved designer themes. Sending the list replaces it. At most 50 items.
settings.themes[].idrequiredstring
settings.themes[].namerequiredstring
settings.themes[].themerequiredobject

Responses

200 Success

{
  "id": string,
  "name": string,
  "slug": string,
  "plan": string,
  "settings": object,
  "smtp": {
    "host": string,
    "port": number or null,
    "username": string
  },
  "inbound": {
    "smtpPort": number or null,
    "cloudflareIngestUrl": string
  },
  "sandboxPending": {
    "scheduledCampaigns": integer,
    "activeAutomationRuns": integer
  }
}
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)

Delete the workspace

DELETE /v1/workspace

Owner only, in a dashboard session. Confirm with your password (and a two-factor code if it is on) and type the workspace name in confirm. Starts a 7-day grace period: the workspace becomes read-only, sending stops, and members are notified. The owner can cancel with POST /v1/workspace/deletion/cancel. After the grace period every row of the workspace is deleted permanently. People keep their accounts.

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

Request body

application/json, required.

FieldTypeDescription
passwordrequiredstringYour current password
codestringTwo-factor code or recovery code, when two-factor authentication is on for your account
confirmrequiredstringThe workspace name, typed exactly

Responses

202 Success

{
  "status": "active" | "pending_deletion",
  "requestedAt": string or null,
  "purgeAt": string or null,
  "requestedBy": {
    "id": string,
    "email": string or null
  }
}
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)

Export all workspace data

POST /v1/workspace/export

Owners and admins (or an admin-scoped live API key). Builds a ZIP in the background: one JSON file per table, CSV files for contacts, messages and events, and a README. Secrets are never included (provider credentials, API key hashes, webhook signing secrets, app password hashes). When it is ready, the person who asked gets an email with a signed download link; the file is kept for 7 days. Only one export runs at a time: while one is running, this returns it.

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

Responses

202 Success

{
  "id": string,
  "object": "workspace_export",
  "status": "queued" | "running" | "ready" | "failed" | "expired",
  "size": number or null,
  "tables": number,
  "rows": number,
  "error": string or null,
  "createdAt": string,
  "completedAt": string or null,
  "expiresAt": string or null,
  "downloadUrl": string or null
}
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)

List data exports

GET /v1/workspace/exports

Owners and admins. Newest first, the last 20.

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

Responses

200 Success

{
  "data": [{
    "id": string,
    "object": "workspace_export",
    "status": "queued" | "running" | "ready" | "failed" | "expired",
    "size": number or null,
    "tables": number,
    "rows": number,
    "error": string or null,
    "createdAt": string,
    "completedAt": string or null,
    "expiresAt": string or null,
    "downloadUrl": string or null
  }]
}
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)

Get a data export

GET /v1/workspace/exports/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "workspace_export",
  "status": "queued" | "running" | "ready" | "failed" | "expired",
  "size": number or null,
  "tables": number,
  "rows": number,
  "error": string or null,
  "createdAt": string,
  "completedAt": string or null,
  "expiresAt": string or null,
  "downloadUrl": string or null
}
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)

Download a data export

GET /v1/workspace/exports/{id}/download

With the signed token from the email (or from downloadUrl), or with an owner or admin session of the workspace. Answers 410 export_expired after the file was removed.

Authentication: None.

Parameters

NameInTypeDescription
idrequiredpathstring
tokenquerystring

Responses

200 Success (application/zip)

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)

Workspace deletion status

GET /v1/workspace/deletion

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

Responses

200 Success

{
  "status": "active" | "pending_deletion",
  "requestedAt": string or null,
  "purgeAt": string or null,
  "requestedBy": {
    "id": string,
    "email": string or null
  }
}
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)

Cancel the workspace deletion

POST /v1/workspace/deletion/cancel

Owner only, before the grace period ends. Sending resumes and members are notified.

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

Responses

200 Success

{
  "status": "active" | "pending_deletion",
  "requestedAt": string or null,
  "purgeAt": string or null,
  "requestedBy": {
    "id": string,
    "email": string or null
  }
}
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)