Automations
Automated journeys: a trigger (list, form, attribute change, custom event, date, campaign engagement, conversion or manual) and steps (emails, waits, branches, attribute and list updates, webhooks, splits), with versions, test runs and reports per step.
List automations
GET /v1/automations
Newest first, with run counts (entered, in progress, completed, exited).
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | |
limit | query | integer | Default 50. 1 to 200. |
status | query | string | Comma-separated: draft, active, paused, stopped. |
q | query | string |
Responses
{
"data": [{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": string or null
}],
"nextCursor": 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)
Create an automation
POST /v1/automations
Created as a draft. Activate it with POST /v1/automations/{id}/activate. A webhook step (it sends contact data to a URL) needs a signed-in admin or a live admin key (403 otherwise), and the workspace owners get a security alert.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
namerequired | string | |
description | string or null | |
recipe | string | Create from a starter recipe (GET /v1/automations/recipes). Fields you send override the recipe. |
trigger | object | |
steps | array of object | At most 200 items. |
settings | object | |
settings.reentry | object | never: once per contact. after: again days after the last entry. always: whenever the contact has no run in progress. |
settings.reentry.moderequired | "never" | "after" | "always" | |
settings.reentry.days | integer or null | |
settings.maxActiveRuns | integer or null | |
settings.frequencyCap | object or null | At most emails automation emails per contact in hours, across every automation. Later emails wait. |
settings.frequencyCap.emailsrequired | integer | |
settings.frequencyCap.hoursrequired | number | |
settings.quietHours | object or null | |
settings.quietHours.startrequired | string | Local time HH:MM in the workspace time zone. |
settings.quietHours.endrequired | string | Local time HH:MM in the workspace time zone. |
settings.testMode | boolean | Emails are logged but not delivered. |
settings.exitOnUnsubscribe | boolean | |
settings.exitConditions | array of object or null | |
settings.includeInactive | boolean | |
settings.includeQualityIssues | boolean | |
settings.migrateRuns | "safe" | "none" | |
goals | array of object | At most 10 items. |
Responses
{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": 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)
Automation recipes
GET /v1/automations/recipes
Complete automations to start from: welcome series, double opt-in follow-up, abandoned cart, win-back, renewal reminder and post-purchase review request. Create one with POST /v1/automations and recipe.
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"data": [{
"id": string,
"name": string,
"description": string,
"definition": object
}]
}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 an automation
GET /v1/automations/{id}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": 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)
Edit an automation
PATCH /v1/automations/{id}
A draft is edited in place. Changing the trigger, steps, settings or goals of an active or paused automation publishes a new version: new entries use it, and runs in progress move to it when their current step still exists with the same type (unless settings.migrateRuns is none). The new definition must be valid (400 automation_invalid).
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
description | string or null | |
trigger | object | |
steps | array of object | At most 200 items. |
settings | object | |
settings.reentry | object | never: once per contact. after: again days after the last entry. always: whenever the contact has no run in progress. |
settings.reentry.moderequired | "never" | "after" | "always" | |
settings.reentry.days | integer or null | |
settings.maxActiveRuns | integer or null | |
settings.frequencyCap | object or null | At most emails automation emails per contact in hours, across every automation. Later emails wait. |
settings.frequencyCap.emailsrequired | integer | |
settings.frequencyCap.hoursrequired | number | |
settings.quietHours | object or null | |
settings.quietHours.startrequired | string | Local time HH:MM in the workspace time zone. |
settings.quietHours.endrequired | string | Local time HH:MM in the workspace time zone. |
settings.testMode | boolean | Emails are logged but not delivered. |
settings.exitOnUnsubscribe | boolean | |
settings.exitConditions | array of object or null | |
settings.includeInactive | boolean | |
settings.includeQualityIssues | boolean | |
settings.migrateRuns | "safe" | "none" | |
goals | array of object | At most 10 items. |
Responses
{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": 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)
Delete an automation
DELETE /v1/automations/{id}
Pause or stop an active automation first. Runs and step history are deleted; emails it sent stay in the email logs.
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)
Check an automation
POST /v1/automations/{id}/validate
Every problem that would stop activation, with the step it belongs to.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"valid": boolean,
"problems": [{
"stepId": string or null,
"field": string,
"message": 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)
Activate (or resume) an automation
POST /v1/automations/{id}/activate
Publishes the current definition as a new version when it changed, then starts accepting entries. A paused automation resumes: runs continue where they were. Fails with 400 automation_invalid and details.problems when something is missing.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": string or null
}Errors: 400, 401, 402, 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.402Payment required (typepayment_required):license_required, a self-hosted server without an active license key (details.buyUrl); on the cloud, only when cloud plans are enabled,plan_required(the workspace has no plan;details.upgradeUrl).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)
Pause an automation
POST /v1/automations/{id}/pause
No new entries, and runs in progress wait where they are until the automation is activated again.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": 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)
Stop an automation
POST /v1/automations/{id}/stop
No new entries, and every run in progress is canceled. It can be activated again later.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": 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)
Enroll contacts
POST /v1/automations/{id}/enroll
Up to 1,000 contacts by id or email, or a whole list or segment (in the background). Re-entry rules, trigger conditions and the most runs in progress apply; unsubscribed, bounced and complained contacts are skipped. Works with any trigger type.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
contactIds | array of string | At most 1000 items. |
emails | array of string (email) | At most 1000 items. |
listId | string | Enroll the whole list in the background. |
segmentId | string | Enroll the whole segment in the background. |
Responses
{
"enrollmentId": string,
"background": boolean,
"enrolled": number,
"notFound": number,
"skipped": map of number
}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)
Test with one contact
POST /v1/automations/{id}/test
dryRun: true (default) walks the current definition for the contact without sending or changing anything and returns the path, with the subject of each email and the time each step would run. dryRun: false starts a real run on the published version with emails sandboxed (logged, not delivered); the automation must be active.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
contactId | string | |
email | string (email) | |
dryRun | boolean | true: preview the path without sending or changing anything. false: a real run on the published version with emails sandboxed. Default true. |
event | object | Dry run: the trigger event to use for {{event.x}} variables and event conditions. |
event.namerequired | string | |
event.properties | object |
Responses
objectErrors: 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)
Automation report
GET /v1/automations/{id}/report
Runs entered, in progress, completed and exited (with reasons); goal reached; email results (sent, delivered, opened, clicked, converted, revenue); and per step: runs at the step now, runs that finished it, outcomes (sent or skipped, yes or no, split paths) and email results. Rates: open and click = unique / delivered.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"automation": {
"id": string,
"object": "automation",
"name": string,
"description": string or null,
"status": "draft" | "active" | "paused" | "stopped",
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"version": number,
"stats": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"activatedAt": string or null,
"createdAt": string,
"updatedAt": string,
"webhookDisabledReason": string or null
},
"runs": {
"entered": number,
"active": number,
"completed": number,
"exited": number,
"failed": number
},
"goalReached": number,
"exitReasons": map of number,
"emails": {
"sent": number,
"delivered": number,
"opened": number,
"clicked": number,
"converted": number,
"revenue": number,
"bounced": number,
"unsubscribed": number,
"complained": number,
"total": number,
"rates": {
"delivery": number,
"open": number,
"click": number,
"conversion": number
}
},
"steps": [{
"stepId": string,
"type": string,
"name": string or null,
"inStep": number,
"completed": number,
"outcomes": map of number,
"emails": {
"sent": number,
…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)
List runs
GET /v1/automations/{id}/runs
One run per contact and entry, newest first.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
cursor | query | string | |
limit | query | integer | Default 50. 1 to 200. |
status | query | string | Comma-separated run statuses. |
stepId | query | string | |
contactId | query | string |
Responses
{
"data": [{
"id": string,
"object": "automation_run",
"automationId": string,
"automationName": string or null,
"version": number,
"contactId": string,
"email": string or null,
"status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
"stepId": string or null,
"waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
"nextRunAt": string or null,
"exitReason": string or null,
"lastError": string or null,
"test": boolean,
"emailsSent": number,
"goalReachedAt": string or null,
"enteredAt": string,
"completedAt": string or null
}],
"nextCursor": 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 run with its step history
GET /v1/automations/{id}/runs/{runId}
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
runIdrequired | path | string |
Responses
{
"id": string,
"object": "automation_run",
"automationId": string,
"automationName": string or null,
"version": number,
"contactId": string,
"email": string or null,
"status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
"stepId": string or null,
"waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
"nextRunAt": string or null,
"exitReason": string or null,
"lastError": string or null,
"test": boolean,
"emailsSent": number,
"goalReachedAt": string or null,
"enteredAt": string,
"completedAt": string or null,
"steps": [{
"stepId": string,
"type": string,
"outcome": string,
"detail": object or null,
"messageId": string or null,
"at": 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)
Remove a contact from an automation
POST /v1/automations/{id}/runs/{runId}/exit
Ends a run in progress (exit reason removed).
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
runIdrequired | path | string |
Responses
{
"id": string,
"object": "automation_run",
"automationId": string,
"automationName": string or null,
"version": number,
"contactId": string,
"email": string or null,
"status": "active" | "waiting" | "completed" | "exited" | "failed" | "canceled",
"stepId": string or null,
"waitingFor": "wait" | "event" | "quiet_hours" | "frequency_cap" | null,
"nextRunAt": string or null,
"exitReason": string or null,
"lastError": string or null,
"test": boolean,
"emailsSent": number,
"goalReachedAt": string or null,
"enteredAt": string,
"completedAt": 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)
Published versions
GET /v1/automations/{id}/versions
Newest first, with the number of runs still in progress on each.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"data": [{
"version": number,
"trigger": object,
"steps": [object],
"settings": object,
"goals": [object],
"createdAt": string,
"runsInProgress": number
}]
}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)
Webhook step signing secret
GET /v1/automations/{id}/signing-secret
Webhook steps sign their requests with this secret: x-onesend-signature: v1=<HMAC-SHA256 of "<x-onesend-timestamp>.<body>">, as outgoing webhooks do.
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"secret": 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)
Rotate the signing secret
POST /v1/automations/{id}/rotate-secret
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"secret": 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)