Docs / API reference

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.

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

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

NameInTypeDescription
cursorquerystring
limitqueryintegerDefault 50. 1 to 200.
statusquerystringComma-separated: draft, active, paused, stopped.
qquerystring

Responses

200 Success

{
  "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
  • 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)

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

application/json, required.

FieldTypeDescription
namerequiredstring
descriptionstring or null
recipestringCreate from a starter recipe (GET /v1/automations/recipes). Fields you send override the recipe.
triggerobject
stepsarray of objectAt most 200 items.
settingsobject
settings.reentryobjectnever: 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.daysinteger or null
settings.maxActiveRunsinteger or null
settings.frequencyCapobject or nullAt most emails automation emails per contact in hours, across every automation. Later emails wait.
settings.frequencyCap.emailsrequiredinteger
settings.frequencyCap.hoursrequirednumber
settings.quietHoursobject or null
settings.quietHours.startrequiredstringLocal time HH:MM in the workspace time zone.
settings.quietHours.endrequiredstringLocal time HH:MM in the workspace time zone.
settings.testModebooleanEmails are logged but not delivered.
settings.exitOnUnsubscribeboolean
settings.exitConditionsarray of object or null
settings.includeInactiveboolean
settings.includeQualityIssuesboolean
settings.migrateRuns"safe" | "none"
goalsarray of objectAt most 10 items.

Responses

201 Success

{
  "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
  • 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)

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

200 Success

{
  "data": [{
    "id": string,
    "name": string,
    "description": string,
    "definition": object
  }]
}
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 an automation

GET /v1/automations/{id}

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 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)

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestring
descriptionstring or null
triggerobject
stepsarray of objectAt most 200 items.
settingsobject
settings.reentryobjectnever: 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.daysinteger or null
settings.maxActiveRunsinteger or null
settings.frequencyCapobject or nullAt most emails automation emails per contact in hours, across every automation. Later emails wait.
settings.frequencyCap.emailsrequiredinteger
settings.frequencyCap.hoursrequirednumber
settings.quietHoursobject or null
settings.quietHours.startrequiredstringLocal time HH:MM in the workspace time zone.
settings.quietHours.endrequiredstringLocal time HH:MM in the workspace time zone.
settings.testModebooleanEmails are logged but not delivered.
settings.exitOnUnsubscribeboolean
settings.exitConditionsarray of object or null
settings.includeInactiveboolean
settings.includeQualityIssuesboolean
settings.migrateRuns"safe" | "none"
goalsarray of objectAt most 10 items.

Responses

200 Success

{
  "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
  • 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 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

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)

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "valid": boolean,
  "problems": [{
    "stepId": string or null,
    "field": string,
    "message": 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)

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 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.
  • 402 Payment required (type payment_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).
  • 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)

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 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)

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 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)

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
contactIdsarray of stringAt most 1000 items.
emailsarray of string (email)At most 1000 items.
listIdstringEnroll the whole list in the background.
segmentIdstringEnroll the whole segment in the background.

Responses

202 Success

{
  "enrollmentId": string,
  "background": boolean,
  "enrolled": number,
  "notFound": number,
  "skipped": map of number
}
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)

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

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
contactIdstring
emailstring (email)
dryRunbooleantrue: preview the path without sending or changing anything. false: a real run on the published version with emails sandboxed. Default true.
eventobjectDry run: the trigger event to use for {{event.x}} variables and event conditions.
event.namerequiredstring
event.propertiesobject

Responses

200 Success

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

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "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
  • 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)

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

NameInTypeDescription
idrequiredpathstring
cursorquerystring
limitqueryintegerDefault 50. 1 to 200.
statusquerystringComma-separated run statuses.
stepIdquerystring
contactIdquerystring

Responses

200 Success

{
  "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
  • 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 run with its step history

GET /v1/automations/{id}/runs/{runId}

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

Parameters

NameInTypeDescription
idrequiredpathstring
runIdrequiredpathstring

Responses

200 Success

{
  "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
  • 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)

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

NameInTypeDescription
idrequiredpathstring
runIdrequiredpathstring

Responses

200 Success

{
  "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
  • 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)

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "data": [{
    "version": number,
    "trigger": object,
    "steps": [object],
    "settings": object,
    "goals": [object],
    "createdAt": string,
    "runsInProgress": number
  }]
}
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)

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

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "secret": 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)

Rotate the signing secret

POST /v1/automations/{id}/rotate-secret

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "secret": 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)