Workspace
Workspace name and settings, such as tracking defaults and the attribution window.
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
{
"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
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)
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
| Field | Type | Description |
|---|---|---|
name | string | |
settings | object | |
settings.trackOpens | boolean | |
settings.trackClicks | boolean | |
settings.trackingDomain | string or null | |
settings.defaultPolicyId | string or null | Routing policy for sends without policy. null or "" clears it. |
settings.sandbox | boolean | |
settings.campaignDailyCap | integer or null | Most campaign emails per day for one campaign, on top of provider limits. null: only provider limits. 1 to 100000000. |
settings.timezone | string | |
settings.attributionWindowDays | integer | 1 to 90. |
settings.companyAddress | string or null | |
settings.brand | object | |
settings.brand.logoUrl | string | |
settings.brand.primary | string | |
settings.brand.accent | string | |
settings.brand.font | string | |
settings.themes | array of object | Saved designer themes. Sending the list replaces it. At most 50 items. |
settings.themes[].idrequired | string | |
settings.themes[].namerequired | string | |
settings.themes[].themerequired | object |
Responses
{
"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
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)
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
| Field | Type | Description |
|---|---|---|
passwordrequired | string | Your current password |
code | string | Two-factor code or recovery code, when two-factor authentication is on for your account |
confirmrequired | string | The workspace name, typed exactly |
Responses
{
"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
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)
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
{
"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
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)
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
{
"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
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)
Get a data export
GET /v1/workspace/exports/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
token | query | string |
Responses
Errors: 400, 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.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)
Workspace deletion status
GET /v1/workspace/deletion
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"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
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)
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
{
"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
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)