Campaigns
Marketing campaigns: draft, schedule, send through your providers, and report.
List campaigns with headline stats
GET /v1/campaigns
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 | |
q | query | string |
Responses
{
"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
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 a draft campaign
POST /v1/campaigns
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
namerequired | string | Internal name, shown in lists and reports. |
subject | string | Subject line. {{variables}} (contact fields such as {{first_name}}) are filled in per recipient. |
previewText | string or null | Preview text shown after the subject in most inboxes. |
fromName | string | Sender name, for example "Acme". |
fromEmail | string | Sender address, for example news@acme.com. Its domain should be verified. |
replyTo | string or null | Reply-To address. |
templateId | string or null | Saved template to send. Its variables are filled from each contact; see GET /v1/campaigns/{id}/check for variables no contact field provides. |
html | string | HTML content when not using a template. |
recipients | object | Contacts in any of listIds or segmentIds, minus excludeListIds. Unsubscribed, bounced and suppressed contacts are skipped. |
recipients.listIds | array of string | Default []. |
recipients.segmentIds | array of string | Default []. |
recipients.excludeListIds | array of string | Default []. |
tracking | object | Open and click tracking, and UTM parameters added to links. |
tracking.opens | boolean | |
tracking.clicks | boolean | |
tracking.utm | object or null | |
tracking.utm.sourcerequired | string | |
tracking.utm.mediumrequired | string | |
tracking.utm.campaignrequired | string | |
currency | string | ISO currency for revenue in reports, for example USD. |
tags | array of string | |
policyId | string or null | Routing policy; defaults to the workspace default. |
delivery | object or null | bestTime: 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.bestTime | boolean | |
delivery.includeQualityIssues | boolean | |
delivery.includeInactive | boolean | |
abTest | object or null | A/B test: 2 to 4 variants sent to a test group first; the winner goes to the rest. null turns it off. |
abTest.enabled | boolean | false turns the test off (same as abTest: null). |
abTest.variants | array of object | At most 4 items. |
abTest.variants[].id | string | a, b, c or d (assigned in order). |
abTest.variants[].name | string or null | |
abTest.variants[].subject | string or null | |
abTest.variants[].previewText | string or null | |
abTest.variants[].fromName | string or null | |
abTest.variants[].templateId | string or null | |
abTest.variants[].html | string or null | |
abTest.testPercent | number | Share 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.durationHours | number | How 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
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
name | string | Internal name, shown in lists and reports. |
subject | string | Subject line. {{variables}} (contact fields such as {{first_name}}) are filled in per recipient. |
previewText | string or null | Preview text shown after the subject in most inboxes. |
fromName | string | Sender name, for example "Acme". |
fromEmail | string | Sender address, for example news@acme.com. Its domain should be verified. |
replyTo | string or null | Reply-To address. |
templateId | string or null | Saved template to send. Its variables are filled from each contact; see GET /v1/campaigns/{id}/check for variables no contact field provides. |
html | string | HTML content when not using a template. |
recipients | object | Contacts in any of listIds or segmentIds, minus excludeListIds. Unsubscribed, bounced and suppressed contacts are skipped. |
recipients.listIds | array of string | Default []. |
recipients.segmentIds | array of string | Default []. |
recipients.excludeListIds | array of string | Default []. |
tracking | object | Open and click tracking, and UTM parameters added to links. |
tracking.opens | boolean | |
tracking.clicks | boolean | |
tracking.utm | object or null | |
tracking.utm.sourcerequired | string | |
tracking.utm.mediumrequired | string | |
tracking.utm.campaignrequired | string | |
currency | string | ISO currency for revenue in reports, for example USD. |
tags | array of string | |
policyId | string or null | Routing policy; defaults to the workspace default. |
delivery | object or null | bestTime: 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.bestTime | boolean | |
delivery.includeQualityIssues | boolean | |
delivery.includeInactive | boolean | |
abTest | object or null | A/B test: 2 to 4 variants sent to a test group first; the winner goes to the rest. null turns it off. |
abTest.enabled | boolean | false turns the test off (same as abTest: null). |
abTest.variants | array of object | At most 4 items. |
abTest.variants[].id | string | a, b, c or d (assigned in order). |
abTest.variants[].name | string or null | |
abTest.variants[].subject | string or null | |
abTest.variants[].previewText | string or null | |
abTest.variants[].fromName | string or null | |
abTest.variants[].templateId | string or null | |
abTest.variants[].html | string or null | |
abTest.testPercent | number | Share 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.durationHours | number | How 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
{
"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
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 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
| 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 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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
Duplicate as a new draft
POST /v1/campaigns/{id}/duplicate
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
torequired | array of string (email) | At most 5 items. |
Responses
{
"messageIds": [string]
}Errors: 400, 401, 402, 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.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)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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
scheduledAtrequired | string or null | |
bestTime | boolean | Send each email at the recipient's best time within 24 hours of scheduledAt (or now). Saved as delivery.bestTime. |
Responses
{
"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
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)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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
Resume a paused campaign
POST /v1/campaigns/{id}/resume
Authentication: Authorization: Bearer with an API key or a session token.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body
| Field | Type | Description |
|---|---|---|
variantIdrequired | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
cursor | query | string | |
limit | query | integer | Default 100. 1 to 500. |
filter | query | "all" | "delivered" | "opened" | "clicked" | "bounced" | "unsubscribed" | "complained" | "converted" | "not_opened" | Default "all". |
q | query | string | |
format | query | "json" | "csv" | Default "json". |
Responses
{
"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
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)
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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
{
"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
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)