Docs / API reference

Campaigns

Marketing campaigns: draft, schedule, send through your providers, and report.

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

List campaigns with headline stats

GET /v1/campaigns

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

Parameters

NameInTypeDescription
cursorquerystring
limitqueryintegerDefault 50. 1 to 200.
statusquerystring
qquerystring

Responses

200 Success

{
  "data": [{
    "id": string,
    "object": "campaign",
    "name": string,
    "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
    "subject": string,
    "previewText": string or null,
    "fromName": string,
    "fromEmail": string,
    "replyTo": string or null,
    "templateId": string or null,
    "recipients": {
      "listIds": [string],
      "segmentIds": [string],
      "excludeListIds": [string]
    },
    "tracking": {
      "opens": boolean,
      "clicks": boolean,
      "utm": { … }
    },
    "currency": string,
    "tags": [string],
    "policyId": string or null,
    "scheduledAt": string or null,
    "sentAt": string or null,
    "estimatedRecipients": number or null,
    "plan": {
      "perDay": number,
      "days": number,
      "unlimited": boolean,
      "limitedBy": "quota" | "warmup" | "pacing",
      "reason": string,
      "domain": string
    },
    "delivery": {
      "bestTime": boolean,
      "includeQualityIssues": boolean,
      "includeInactive": boolean
    },
    "pausedReason": {
      "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
      "auto": boolean,
      "message": string,
      "at": string,
      "value": number,
      "threshold": number,
      "sample": number
    },
    "abTest": {
      "variants": [{ … }],
      "testPercent": number,
      "metric": "open" | "click" | "conversion" | "revenue",
      "durationHours": number,
      "winnerSelection": "auto" | "manual",
      "phase": "testing" | "waiting_for_pick" | "winner_sent" | null,
      "testStartedAt": string or null,
      "decideAt": string or null,
      "winnerId": 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 a draft campaign

POST /v1/campaigns

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

Request body

application/json, required.

FieldTypeDescription
namerequiredstringInternal name, shown in lists and reports.
subjectstringSubject line. {{variables}} (contact fields such as {{first_name}}) are filled in per recipient.
previewTextstring or nullPreview text shown after the subject in most inboxes.
fromNamestringSender name, for example "Acme".
fromEmailstringSender address, for example news@acme.com. Its domain should be verified.
replyTostring or nullReply-To address.
templateIdstring or nullSaved template to send. Its variables are filled from each contact; see GET /v1/campaigns/{id}/check for variables no contact field provides.
htmlstringHTML content when not using a template.
recipientsobjectContacts in any of listIds or segmentIds, minus excludeListIds. Unsubscribed, bounced and suppressed contacts are skipped.
recipients.listIdsarray of stringDefault [].
recipients.segmentIdsarray of stringDefault [].
recipients.excludeListIdsarray of stringDefault [].
trackingobjectOpen and click tracking, and UTM parameters added to links.
tracking.opensboolean
tracking.clicksboolean
tracking.utmobject or null
tracking.utm.sourcerequiredstring
tracking.utm.mediumrequiredstring
tracking.utm.campaignrequiredstring
currencystringISO currency for revenue in reports, for example USD.
tagsarray of string
policyIdstring or nullRouting policy; defaults to the workspace default.
deliveryobject or nullbestTime: send each email at the hour the recipient usually opens (within 24 hours of the start). includeQualityIssues and includeInactive include contacts that campaigns skip by default.
delivery.bestTimeboolean
delivery.includeQualityIssuesboolean
delivery.includeInactiveboolean
abTestobject or nullA/B test: 2 to 4 variants sent to a test group first; the winner goes to the rest. null turns it off.
abTest.enabledbooleanfalse turns the test off (same as abTest: null).
abTest.variantsarray of objectAt most 4 items.
abTest.variants[].idstringa, b, c or d (assigned in order).
abTest.variants[].namestring or null
abTest.variants[].subjectstring or null
abTest.variants[].previewTextstring or null
abTest.variants[].fromNamestring or null
abTest.variants[].templateIdstring or null
abTest.variants[].htmlstring or null
abTest.testPercentnumberShare of the recipients in the test group, split evenly between the variants. Default 20. 5 to 50.
abTest.metric"open" | "click" | "conversion" | "revenue"How the winner is picked: open, click or conversion rate, or revenue per delivered email. Default open.
abTest.durationHoursnumberHow long the test group gets before the winner is picked. Default 4. 1 to 168.
abTest.winnerSelection"auto" | "manual"auto: the leading variant is sent to the rest when the test ends. manual: the campaign waits for POST /v1/campaigns/{id}/ab-test/winner.

Responses

201 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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)

Get a campaign

GET /v1/campaigns/{id}

Drafts include a live recipient estimate and sending plan; started campaigns include stats.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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 a campaign

PATCH /v1/campaigns/{id}

Drafts and scheduled campaigns can be edited. Once sending has started only the name and tags can change.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
namestringInternal name, shown in lists and reports.
subjectstringSubject line. {{variables}} (contact fields such as {{first_name}}) are filled in per recipient.
previewTextstring or nullPreview text shown after the subject in most inboxes.
fromNamestringSender name, for example "Acme".
fromEmailstringSender address, for example news@acme.com. Its domain should be verified.
replyTostring or nullReply-To address.
templateIdstring or nullSaved template to send. Its variables are filled from each contact; see GET /v1/campaigns/{id}/check for variables no contact field provides.
htmlstringHTML content when not using a template.
recipientsobjectContacts in any of listIds or segmentIds, minus excludeListIds. Unsubscribed, bounced and suppressed contacts are skipped.
recipients.listIdsarray of stringDefault [].
recipients.segmentIdsarray of stringDefault [].
recipients.excludeListIdsarray of stringDefault [].
trackingobjectOpen and click tracking, and UTM parameters added to links.
tracking.opensboolean
tracking.clicksboolean
tracking.utmobject or null
tracking.utm.sourcerequiredstring
tracking.utm.mediumrequiredstring
tracking.utm.campaignrequiredstring
currencystringISO currency for revenue in reports, for example USD.
tagsarray of string
policyIdstring or nullRouting policy; defaults to the workspace default.
deliveryobject or nullbestTime: send each email at the hour the recipient usually opens (within 24 hours of the start). includeQualityIssues and includeInactive include contacts that campaigns skip by default.
delivery.bestTimeboolean
delivery.includeQualityIssuesboolean
delivery.includeInactiveboolean
abTestobject or nullA/B test: 2 to 4 variants sent to a test group first; the winner goes to the rest. null turns it off.
abTest.enabledbooleanfalse turns the test off (same as abTest: null).
abTest.variantsarray of objectAt most 4 items.
abTest.variants[].idstringa, b, c or d (assigned in order).
abTest.variants[].namestring or null
abTest.variants[].subjectstring or null
abTest.variants[].previewTextstring or null
abTest.variants[].fromNamestring or null
abTest.variants[].templateIdstring or null
abTest.variants[].htmlstring or null
abTest.testPercentnumberShare of the recipients in the test group, split evenly between the variants. Default 20. 5 to 50.
abTest.metric"open" | "click" | "conversion" | "revenue"How the winner is picked: open, click or conversion rate, or revenue per delivered email. Default open.
abTest.durationHoursnumberHow long the test group gets before the winner is picked. Default 4. 1 to 168.
abTest.winnerSelection"auto" | "manual"auto: the leading variant is sent to the rest when the test ends. manual: the campaign waits for POST /v1/campaigns/{id}/ab-test/winner.

Responses

200 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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 a campaign

DELETE /v1/campaigns/{id}

A campaign that is sending must be paused or canceled first. Emails already sent stay in the logs and stay viewable: the campaign disappears from the API, but what is needed to show those emails is kept.

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 a campaign before sending

GET /v1/campaigns/{id}/check

What would stop the campaign from being scheduled (problems), and template {{variables}} that no contact provides (missingVariables). Show these in a review step before sending.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "ready": boolean,
  "problems": [string],
  "missingVariables": [{
    "path": string,
    "usedIn": ["subject" | "preheader" | "content"]
  }],
  "warnings": [{
    "code": "missing_variables" | "transactional_template",
    "message": string,
    "variables": [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)

Duplicate as a new draft

POST /v1/campaigns/{id}/duplicate

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

201 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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)

Send a test email

POST /v1/campaigns/{id}/test

Sent through your routing policy like a real send, with "[Test]" in the subject. Not counted in campaign stats.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
torequiredarray of string (email)At most 5 items.

Responses

202 Success

{
  "messageIds": [string]
}
Errors: 400, 401, 402, 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.
  • 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)
  • 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)

Schedule, or send now

POST /v1/campaigns/{id}/schedule

scheduledAt: null sends now. Recipients are fixed when sending starts. When the audience is larger than today’s remaining quota on providers that allow campaigns, the rest is sent on the following days. Not available to test-mode keys.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
scheduledAtrequiredstring or null
bestTimebooleanSend each email at the recipient's best time within 24 hours of scheduledAt (or now). Saved as delivery.bestTime.

Responses

202 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": string or null,
  …
Errors: 400, 401, 402, 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.
  • 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)
  • 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)

Pause sending (emails not yet handed to a provider are held)

POST /v1/campaigns/{id}/pause

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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)

Resume a paused campaign

POST /v1/campaigns/{id}/resume

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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)

Cancel (emails not yet handed to a provider are dropped)

POST /v1/campaigns/{id}/cancel

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "id": string,
  "object": "campaign",
  "name": string,
  "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
  "subject": string,
  "previewText": string or null,
  "fromName": string,
  "fromEmail": string,
  "replyTo": string or null,
  "templateId": string or null,
  "recipients": {
    "listIds": [string],
    "segmentIds": [string],
    "excludeListIds": [string]
  },
  "tracking": {
    "opens": boolean,
    "clicks": boolean,
    "utm": {
      "source": string,
      "medium": string,
      "campaign": string
    }
  },
  "currency": string,
  "tags": [string],
  "policyId": string or null,
  "scheduledAt": string or null,
  "sentAt": string or null,
  "estimatedRecipients": number or null,
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": "quota" | "warmup" | "pacing",
    "reason": string,
    "domain": string
  },
  "delivery": {
    "bestTime": boolean,
    "includeQualityIssues": boolean,
    "includeInactive": boolean
  },
  "pausedReason": {
    "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
    "auto": boolean,
    "message": string,
    "at": string,
    "value": number,
    "threshold": number,
    "sample": number
  },
  "abTest": {
    "variants": [{
      "id": string,
      "name": string or null,
      "subject": string or null,
      "previewText": string or null,
      "fromName": 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)

A/B test results

GET /v1/campaigns/{id}/ab-test

Results per variant, the leader and whether the difference is likely to be chance (two-proportion z-test, 95%).

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "metric": "open" | "click" | "conversion" | "revenue",
  "testPercent": number,
  "durationHours": number,
  "winnerSelection": "auto" | "manual",
  "phase": string or null,
  "testStartedAt": string or null,
  "decideAt": string or null,
  "winnerId": string or null,
  "decidedAt": string or null,
  "decidedBy": string or null,
  "held": number,
  "variants": [{
    "id": string,
    "name": string,
    "subject": string or null,
    "recipients": number,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "conversions": number,
    "revenue": number,
    "rates": {
      "open": number,
      "click": number,
      "conversion": number,
      "revenuePerEmail": number
    },
    "value": number,
    "success": number,
    "winner": boolean
  }],
  "leader": string or null,
  "comparison": {
    "leader": string,
    "runnerUp": string,
    "z": number,
    "pValue": number,
    "significant": boolean
  },
  "summary": 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)

Pick the A/B test winner

POST /v1/campaigns/{id}/ab-test/winner

Sends the winning variant to the rest of the recipients now. Needed when winnerSelection is manual; with auto it ends the test early.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Request body

application/json, required.

FieldTypeDescription
variantIdrequiredstring

Responses

200 Success

{
  "metric": "open" | "click" | "conversion" | "revenue",
  "testPercent": number,
  "durationHours": number,
  "winnerSelection": "auto" | "manual",
  "phase": string or null,
  "testStartedAt": string or null,
  "decideAt": string or null,
  "winnerId": string or null,
  "decidedAt": string or null,
  "decidedBy": string or null,
  "held": number,
  "variants": [{
    "id": string,
    "name": string,
    "subject": string or null,
    "recipients": number,
    "sent": number,
    "delivered": number,
    "uniqueOpens": number,
    "uniqueClicks": number,
    "conversions": number,
    "revenue": number,
    "rates": {
      "open": number,
      "click": number,
      "conversion": number,
      "revenuePerEmail": number
    },
    "value": number,
    "success": number,
    "winner": boolean
  }],
  "leader": string or null,
  "comparison": {
    "leader": string,
    "runnerUp": string,
    "z": number,
    "pValue": number,
    "significant": boolean
  },
  "summary": string
}
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
  • 400 Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Type invalid_request.
  • 401 Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Type unauthorized.
  • 403 The API key's permission does not allow this operation (insufficient_scope; configuration needs an admin key), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missing X-OneSend-Client: dashboard (csrf_header_required). Type forbidden.
  • 404 The resource does not exist in this workspace (not_found)
  • 409 The request conflicts with the current state, for example a duplicate name or a reused Idempotency-Key (conflict)
  • 413 The request body is larger than the limit for this endpoint (payload_too_large)
  • 415 The body is not sent as Content-Type: application/json (unsupported_media_type)
  • 429 Too many requests; retry after the time in the Retry-After header (rate_limited)
  • 500 Unexpected server error (internal)

Campaign report

GET /v1/campaigns/{id}/report

Rates: delivery = delivered/sent · open = unique opens/delivered · click = unique clicks/delivered · click-to-open = unique clicks/unique opens · bounce = (hard+soft)/sent · unsubscribe, complaint and conversion = count/delivered. "Delivered" is accepted by the provider and not bounced. Conversions count recipients who converted at least once; revenue sums every conversion.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "campaign": {
    "id": string,
    "object": "campaign",
    "name": string,
    "status": "draft" | "scheduled" | "sending" | "sent" | "paused" | "canceled" | "failed",
    "subject": string,
    "previewText": string or null,
    "fromName": string,
    "fromEmail": string,
    "replyTo": string or null,
    "templateId": string or null,
    "recipients": {
      "listIds": [string],
      "segmentIds": [string],
      "excludeListIds": [string]
    },
    "tracking": {
      "opens": boolean,
      "clicks": boolean,
      "utm": {
        "source": string,
        "medium": string,
        "campaign": string
      }
    },
    "currency": string,
    "tags": [string],
    "policyId": string or null,
    "scheduledAt": string or null,
    "sentAt": string or null,
    "estimatedRecipients": number or null,
    "plan": {
      "perDay": number,
      "days": number,
      "unlimited": boolean,
      "limitedBy": "quota" | "warmup" | "pacing",
      "reason": string,
      "domain": string
    },
    "delivery": {
      "bestTime": boolean,
      "includeQualityIssues": boolean,
      "includeInactive": boolean
    },
    "pausedReason": {
      "code": "bounce_rate" | "complaint_rate" | "workspace_guard" | "manual",
      "auto": boolean,
      "message": string,
      "at": string,
      "value": number,
      "threshold": number,
      "sample": number
    },
    "abTest": {
      "variants": [{ … }],
      "testPercent": number,
      "metric": "open" | "click" | "conversion" | "revenue",
      "durationHours": number,
      "winnerSelection": "auto" | "manual",
  …
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)

Recipient activity (JSON or CSV)

GET /v1/campaigns/{id}/recipients

cursor is a row offset: pass back nextCursor unchanged. format=csv returns every matching row as a file.

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

Parameters

NameInTypeDescription
idrequiredpathstring
cursorquerystring
limitqueryintegerDefault 100. 1 to 500.
filterquery"all" | "delivered" | "opened" | "clicked" | "bounced" | "unsubscribed" | "complained" | "converted" | "not_opened"Default "all".
qquerystring
formatquery"json" | "csv"Default "json".

Responses

200 Success

{
  "data": [{
    "contactId": string or null,
    "connectionId": string or null,
    "connectionName": string or null,
    "email": string,
    "messageId": string or null,
    "status": string,
    "provider": string or null,
    "openedAt": string or null,
    "clickedAt": string or null,
    "convertedAt": string or null,
    "bounceType": "hard" | "soft" | null
  }],
  "nextCursor": string or null,
  "total": 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)

Safeguards that apply to a campaign

GET /v1/campaigns/{id}/safeguards

For the review step: the automatic pause thresholds, warm-up and pacing of the sending domain and the combined sending plan, contacts left out for address problems or inactivity, the workspace guard and the best time to send.

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

Parameters

NameInTypeDescription
idrequiredpathstring

Responses

200 Success

{
  "items": [{
    "code": string,
    "title": string,
    "detail": string,
    "level": "info" | "warning" | "blocking"
  }],
  "plan": {
    "perDay": number,
    "days": number,
    "unlimited": boolean,
    "limitedBy": string,
    "reason": string
  },
  "excluded": {
    "quality": number,
    "inactive": number
  },
  "guard": {
    "blocked": boolean,
    "code": string or null,
    "message": string or null,
    "blockedAt": string or null,
    "acknowledgedAt": string or null,
    "bounceRate": number,
    "complaintRate": number,
    "sample": number
  },
  "bestTime": {
    "hour": number or null,
    "localHour": number or null,
    "timezone": string,
    "histogram": [number],
    "opens": number,
    "suggestion": 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)