API reference

Campaigns

Send one message to many recipients, on a schedule and at a controlled rate, and follow the progress.

Create a campaign#

POST/v1/campaignsScopecampaigns:write

Creates a campaign as a draft. Nothing is sent until you launch it, unless the request carries launch: true: the campaign is then created and launched in one call, with the checks and errors of POST /v1/campaigns/{id}/launch, and nothing is kept when the launch is refused. A template plus the recipients in audience.recipients is all an automation needs.

The message has the same shape as the body of POST /v1/messages without channel and to: type plus the content object under the key named by type. Strings in it may contain merge tags such as {{first_name}}; tags that name no contact field or defined attribute are rejected here, not at send time. merge_fallbacks gives the value used when a recipient has none.

A live WhatsApp campaign must use an approved template: the template is looked up on the channel, and a missing or unapproved one fails with 422 template_not_approved. With a test key the campaign runs against a sandbox channel (ch_test_<type>), delivers nothing and is free.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

namestringRequired
Name of the campaign.
1 to 120 characters
channelstringRequired
Channel ID. With a test key, a sandbox channel such as ch_test_whatsapp.
audienceobjectRequired
Who to send to: a segment, a list, contacts with certain tags, or recipients supplied with the request.
Segment · show attributes · hide attributes
- typestringRequired
  Value: segment
- segment_idstringRequired
  Segment ID. The rules are evaluated when sending starts.
List · show attributes · hide attributes
- typestringRequired
  Value: list
- list_idstringRequired
  Contact list ID.
Tags · show attributes · hide attributes
- typestringRequired
  Value: tags
- tagsarray of stringsRequired
  Contacts carrying these tags.
  1 to 20 items
- matchstringOptional
  Whether a contact needs one of the tags or all of them.
  Default: any
  Possible valuesanyall
Pasted recipients · show attributes · hide attributes
- typestringRequired
  Value: adhoc
- recipientsarray of objectsRequired
  Up to 10,000 recipients.
  1 to 10000 items
  Show child attributesHide child attributes
  tostringRequired
  Recipient identifier on the channel: a phone number for WhatsApp and SMS.
  1 to 255 characters
  first_namestringOptional
  Given name, for {{first_name}}.
  Up to 100 characters
  last_namestringOptional
  Family name, for {{last_name}}.
  Up to 100 characters
  variablesobjectOptional
  Merge values of this recipient by tag.
- save_as_contactsbooleanOptional
  Save the recipients as contacts when sending starts (phone channels).
  Default: false
messageobjectRequired
What is sent: type and the content object under the key named by type, exactly as in POST /v1/messages. Strings may contain merge tags such as {{first_name}}, {{last_name}}, {{full_name}}, {{phone}}, {{email}}, {{locale}} and {{attributes.<key>}}; each recipient gets their own value. Unknown tags are rejected when the campaign is saved.
Show child attributesHide child attributes
- typestringRequired
  Message type. Must be one of the capabilities of the channel. Live WhatsApp campaigns must use template.
merge_fallbacksobjectOptional
Value for a merge tag when a recipient has none, by tag.
require_opt_inbooleanOptional
Only message contacts whose consent for the channel type is opted_in.
Default: false
consent_declaredbooleanOptional
Declare that the recipients agreed to receive messages from you on this channel. Can also be sent when launching.
Default: false
launchbooleanOptional
Create and launch in one request. Needs consent_declared: true. When the launch is refused, nothing is created.
Default: false
allow_insufficient_fundsbooleanOptional
With launch: start although the funds do not cover every recipient. The campaign pauses when they run out.
Default: false
scheduleobjectOptional
When the campaign sends.
Show child attributesHide child attributes
- send_atstring or nullOptional
  When sending starts. null starts as soon as the campaign is launched.
- timezonestringOptional
  IANA time zone of send_window. Defaults to the time zone of the account.
- send_windowobject or nullOptional
  Local-time window outside which nothing is sent (quiet hours). A window whose end is not after its start runs overnight.
  Show child attributesHide child attributes
  startstringRequired
  Start, HH:MM.
  endstringRequired
  End, HH:MM.
- recipient_timezonebooleanOptional
  Apply send_window in the time zone of each contact that has one, instead of timezone.
throttle_per_secondintegerOptional
Most messages per second. Defaults to 20 and is capped by the per-channel limit.
1 to 100

Responses

201
The draft campaign, or the launched campaign when launch was true.
400
Invalid body. With launch: no consent declaration, no reachable recipient, or a size limit.
parameter_missing parameter_invalid unsupported_message_type invalid_json consent_required campaign_limit_exceeded
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
402
With launch: credits and wallet do not cover every recipient and allow_insufficient_funds was not set. Nothing was created.
insufficient_balance
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The channel, segment or list does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
422
The WhatsApp template is missing or not approved, or the channel is not connected and its templates cannot be read.
template_not_approved channel_not_connected
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error
503
The delivery layer is temporarily unavailable. Any charge was reversed and nothing was created.
upstream_unavailable

POST/v1/campaigns

Example

curl https://api.omnimessage.co/v1/campaigns \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October delivery update",
    "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
    "audience": {
      "type": "list",
      "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
    },
    "message": {
      "type": "template",
      "template": {
        "name": "order_update",
        "language": {
          "code": "en"
        },
        "components": [
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "{{first_name}}"
              },
              {
                "type": "text",
                "text": "on its way"
              }
            ]
          }
        ]
      }
    },
    "merge_fallbacks": {
      "first_name": "there"
    },
    "consent_declared": true,
    "schedule": {
      "send_at": null,
      "timezone": "Asia/Dubai",
      "send_window": {
        "start": "09:00",
        "end": "20:00"
      },
      "recipient_timezone": true
    },
    "throttle_per_second": 20
  }'

Response · 201

{
  "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
  "object": "campaign",
  "mode": "live",
  "name": "October delivery update",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "status": "draft",
  "pause_reason": null,
  "failure_reason": null,
  "audience": {
    "type": "list",
    "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
  },
  "message": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "{{first_name}}"
            },
            {
              "type": "text",
              "text": "on its way"
            }
          ]
        }
      ]
    }
  },
  "merge_fallbacks": {
    "first_name": "there"
  },
  "require_opt_in": false,
  "consent_declared": true,
  "schedule": {
    "send_at": null,
    "timezone": "Asia/Dubai",
    "send_window": {
      "start": "09:00",
      "end": "20:00"
    },
    "recipient_timezone": true
  },
  "throttle_per_second": 20,
  "counters": {
    "total": 0,
    "queued": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "skipped": 0,
    "cancelled": 0,
    "skip_reasons": {}
  },
  "cost": {
    "currency": "USD",
    "estimated_wallet_micros": null,
    "estimated_credits": null,
    "wallet_micros": 0,
    "package_credits": 0
  },
  "created_at": "2026-10-05T09:00:00.000Z",
  "launched_at": null,
  "started_at": null,
  "paused_at": null,
  "completed_at": null,
  "cancelled_at": null
}

List campaigns#

GET/v1/campaignsScopecampaigns:read

Returns the campaigns of the key mode, newest first.

Query parameters

statusstringOptional
Only campaigns in this status.
Possible valuesdraftscheduledqueuedsendingpausedcompletedcancelledfailed
limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of campaigns.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/campaigns

curl "https://api.omnimessage.co/v1/campaigns?status=draft" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
      "object": "campaign",
      "mode": "live",
      "name": "October delivery update",
      "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
      "channel_type": "whatsapp",
      "status": "sending",
      "pause_reason": null,
      "failure_reason": null,
      "audience": {
        "type": "list",
        "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
      },
      "message": {
        "type": "template",
        "template": {
          "name": "order_update",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "{{first_name}}"
                },
                {
                  "type": "text",
                  "text": "on its way"
                }
              ]
            }
          ]
        }
      },
      "merge_fallbacks": {
        "first_name": "there"
      },
      "require_opt_in": false,
      "consent_declared": true,
      "schedule": {
        "send_at": null,
        "timezone": "Asia/Dubai",
        "send_window": {
          "start": "09:00",
          "end": "20:00"
        },
        "recipient_timezone": true
      },
      "throttle_per_second": 20,
      "counters": {
        "total": 1280,
        "queued": 640,
        "sent": 598,
        "delivered": 571,
        "read": 302,
        "failed": 9,
        "skipped": 33,
        "cancelled": 0,
        "skip_reasons": {
          "unsubscribed": 21,
          "no_identifier": 12
        }
      },
      "cost": {
        "currency": "USD",
        "estimated_wallet_micros": 247000,
        "estimated_credits": 1000,
        "wallet_micros": 0,
        "package_credits": 598
      },
      "created_at": "2026-10-05T09:00:00.000Z",
      "launched_at": "2026-10-05T09:05:00.000Z",
      "started_at": "2026-10-05T09:05:02.000Z",
      "paused_at": null,
      "completed_at": null,
      "cancelled_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a campaign#

GET/v1/campaigns/{id}Scopecampaigns:read

Returns one campaign with its counters and cost. Poll it, or subscribe to the campaign.* events, to follow progress.

Path parameters

idstringRequired
Campaign ID.

Responses

200
The campaign.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/campaigns/{id}

curl https://api.omnimessage.co/v1/campaigns/cmp_5Cf8hK1mP4rT7vY0aD3g \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
  "object": "campaign",
  "mode": "live",
  "name": "October delivery update",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "status": "sending",
  "pause_reason": null,
  "failure_reason": null,
  "audience": {
    "type": "list",
    "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
  },
  "message": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "{{first_name}}"
            },
            {
              "type": "text",
              "text": "on its way"
            }
          ]
        }
      ]
    }
  },
  "merge_fallbacks": {
    "first_name": "there"
  },
  "require_opt_in": false,
  "consent_declared": true,
  "schedule": {
    "send_at": null,
    "timezone": "Asia/Dubai",
    "send_window": {
      "start": "09:00",
      "end": "20:00"
    },
    "recipient_timezone": true
  },
  "throttle_per_second": 20,
  "counters": {
    "total": 1280,
    "queued": 640,
    "sent": 598,
    "delivered": 571,
    "read": 302,
    "failed": 9,
    "skipped": 33,
    "cancelled": 0,
    "skip_reasons": {
      "unsubscribed": 21,
      "no_identifier": 12
    }
  },
  "cost": {
    "currency": "USD",
    "estimated_wallet_micros": 247000,
    "estimated_credits": 1000,
    "wallet_micros": 0,
    "package_credits": 598
  },
  "created_at": "2026-10-05T09:00:00.000Z",
  "launched_at": "2026-10-05T09:05:00.000Z",
  "started_at": "2026-10-05T09:05:02.000Z",
  "paused_at": null,
  "completed_at": null,
  "cancelled_at": null
}

List the recipients of a campaign#

GET/v1/campaigns/{id}/recipientsScopecampaigns:read

Returns the recipients in the order of the audience snapshot, with the outcome of each. The list is empty until the campaign has been launched and its snapshot taken.

Path parameters

idstringRequired
Campaign ID.

Query parameters

statusstringOptional
Only recipients in this status.
Possible valuespendingsentdeliveredreadfailedskippedcancelled
tostringOptional
Only the recipient with this identifier.
limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of recipients.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/campaigns/{id}/recipients

curl "https://api.omnimessage.co/v1/campaigns/cmp_5Cf8hK1mP4rT7vY0aD3g/recipients?status=failed" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "184467",
      "object": "campaign_recipient",
      "contact_id": "ct_8Jk3mP6qR9sT2vW5xY1z",
      "to": "+971501234567",
      "name": "Layla Haddad",
      "status": "delivered",
      "skip_reason": null,
      "message_id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "error": null,
      "variables": {
        "first_name": "Layla"
      },
      "sent_at": "2026-10-05T09:05:03.120Z",
      "delivered_at": "2026-10-05T09:05:04.871Z",
      "read_at": null,
      "failed_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "184467"
}

Launch a campaign#

POST/v1/campaigns/{id}/launchScopecampaigns:write

Starts a draft. The campaign becomes scheduled when schedule.send_at is in the future, otherwise queued while the audience snapshot is taken in the background, then sending.

Before anything is sent the request checks the consent declaration (400 consent_required), that the channel is connected, the WhatsApp template, the size limits (400 campaign_limit_exceeded) and the funds: when credits and wallet do not cover every recipient the request fails with 402 insufficient_balance unless allow_insufficient_funds is true, in which case the campaign pauses when the funds run out.

Each message is charged when it is sent, exactly like POST /v1/messages. Provider fees, such as Meta conversation fees, are billed by the provider and are separate.

Path parameters

idstringRequired
Campaign ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

consent_declaredbooleanOptional
Declare that the recipients agreed to be contacted, if the campaign does not carry the declaration yet.
allow_insufficient_fundsbooleanOptional
Launch although the funds do not cover every recipient. The campaign then pauses with pause_reason: "insufficient_balance" when they run out.
Default: false

Responses

200
The launched campaign.
400
Invalid body, no consent declaration, an audience without any reachable recipient (parameter_invalid, param: "audience"), or a size limit.
parameter_invalid invalid_json consent_required campaign_limit_exceeded
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
402
Credits and wallet do not cover every recipient and allow_insufficient_funds was not set.
insufficient_balance
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
campaign_state_invalid idempotency_key_in_use idempotency_key_reused
422
Unprocessable.
channel_not_connected template_not_approved
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error
503
The delivery layer is temporarily unavailable. Any charge was reversed and nothing was created.
upstream_unavailable

POST/v1/campaigns/{id}/launch

curl https://api.omnimessage.co/v1/campaigns/cmp_5Cf8hK1mP4rT7vY0aD3g/launch \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "consent_declared": true
  }'

Response · 200

{
  "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
  "object": "campaign",
  "mode": "live",
  "name": "October delivery update",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "status": "queued",
  "pause_reason": null,
  "failure_reason": null,
  "audience": {
    "type": "list",
    "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
  },
  "message": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "{{first_name}}"
            },
            {
              "type": "text",
              "text": "on its way"
            }
          ]
        }
      ]
    }
  },
  "merge_fallbacks": {
    "first_name": "there"
  },
  "require_opt_in": false,
  "consent_declared": true,
  "schedule": {
    "send_at": null,
    "timezone": "Asia/Dubai",
    "send_window": {
      "start": "09:00",
      "end": "20:00"
    },
    "recipient_timezone": true
  },
  "throttle_per_second": 20,
  "counters": {
    "total": 0,
    "queued": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "skipped": 0,
    "cancelled": 0,
    "skip_reasons": {}
  },
  "cost": {
    "currency": "USD",
    "estimated_wallet_micros": 247000,
    "estimated_credits": 1000,
    "wallet_micros": 0,
    "package_credits": 0
  },
  "created_at": "2026-10-05T09:00:00.000Z",
  "launched_at": "2026-10-05T09:05:00.000Z",
  "started_at": null,
  "paused_at": null,
  "completed_at": null,
  "cancelled_at": null
}

Pause a campaign#

POST/v1/campaigns/{id}/pauseScopecampaigns:write

Stops a scheduled, queued or sending campaign. Messages already handed to the channel still go out; nothing new is sent, usually within a second or two.

Path parameters

idstringRequired
Campaign ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Responses

200
The paused campaign.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
campaign_state_invalid idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/campaigns/{id}/pause

curl -X POST https://api.omnimessage.co/v1/campaigns/cmp_5Cf8hK1mP4rT7vY0aD3g/pause \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
  "object": "campaign",
  "mode": "live",
  "name": "October delivery update",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "status": "paused",
  "pause_reason": "user",
  "failure_reason": null,
  "audience": {
    "type": "list",
    "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
  },
  "message": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "{{first_name}}"
            },
            {
              "type": "text",
              "text": "on its way"
            }
          ]
        }
      ]
    }
  },
  "merge_fallbacks": {
    "first_name": "there"
  },
  "require_opt_in": false,
  "consent_declared": true,
  "schedule": {
    "send_at": null,
    "timezone": "Asia/Dubai",
    "send_window": {
      "start": "09:00",
      "end": "20:00"
    },
    "recipient_timezone": true
  },
  "throttle_per_second": 20,
  "counters": {
    "total": 1280,
    "queued": 640,
    "sent": 598,
    "delivered": 571,
    "read": 302,
    "failed": 9,
    "skipped": 33,
    "cancelled": 0,
    "skip_reasons": {
      "unsubscribed": 21,
      "no_identifier": 12
    }
  },
  "cost": {
    "currency": "USD",
    "estimated_wallet_micros": 247000,
    "estimated_credits": 1000,
    "wallet_micros": 0,
    "package_credits": 598
  },
  "created_at": "2026-10-05T09:00:00.000Z",
  "launched_at": "2026-10-05T09:05:00.000Z",
  "started_at": "2026-10-05T09:05:02.000Z",
  "paused_at": "2026-10-05T09:12:30.000Z",
  "completed_at": null,
  "cancelled_at": null
}

Resume a campaign#

POST/v1/campaigns/{id}/resumeScopecampaigns:write

Continues a paused campaign where it stopped. A live campaign needs funds for at least one message, otherwise the request fails with 402 insufficient_balance.

Path parameters

idstringRequired
Campaign ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Responses

200
The resumed campaign.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
402
No package credits remain and the wallet cannot cover one message.
insufficient_balance
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
campaign_state_invalid idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/campaigns/{id}/resume

curl -X POST https://api.omnimessage.co/v1/campaigns/cmp_5Cf8hK1mP4rT7vY0aD3g/resume \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
  "object": "campaign",
  "mode": "live",
  "name": "October delivery update",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "status": "sending",
  "pause_reason": null,
  "failure_reason": null,
  "audience": {
    "type": "list",
    "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
  },
  "message": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "{{first_name}}"
            },
            {
              "type": "text",
              "text": "on its way"
            }
          ]
        }
      ]
    }
  },
  "merge_fallbacks": {
    "first_name": "there"
  },
  "require_opt_in": false,
  "consent_declared": true,
  "schedule": {
    "send_at": null,
    "timezone": "Asia/Dubai",
    "send_window": {
      "start": "09:00",
      "end": "20:00"
    },
    "recipient_timezone": true
  },
  "throttle_per_second": 20,
  "counters": {
    "total": 1280,
    "queued": 640,
    "sent": 598,
    "delivered": 571,
    "read": 302,
    "failed": 9,
    "skipped": 33,
    "cancelled": 0,
    "skip_reasons": {
      "unsubscribed": 21,
      "no_identifier": 12
    }
  },
  "cost": {
    "currency": "USD",
    "estimated_wallet_micros": 247000,
    "estimated_credits": 1000,
    "wallet_micros": 0,
    "package_credits": 598
  },
  "created_at": "2026-10-05T09:00:00.000Z",
  "launched_at": "2026-10-05T09:05:00.000Z",
  "started_at": "2026-10-05T09:05:02.000Z",
  "paused_at": null,
  "completed_at": null,
  "cancelled_at": null
}

Cancel a campaign#

POST/v1/campaigns/{id}/cancelScopecampaigns:write

Ends a campaign for good. Recipients that were not sent to yet become cancelled; messages already sent are not recalled and stay charged.

Path parameters

idstringRequired
Campaign ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Responses

200
The cancelled campaign.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
campaign_state_invalid idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/campaigns/{id}/cancel

curl -X POST https://api.omnimessage.co/v1/campaigns/cmp_5Cf8hK1mP4rT7vY0aD3g/cancel \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "cmp_5Cf8hK1mP4rT7vY0aD3g",
  "object": "campaign",
  "mode": "live",
  "name": "October delivery update",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "status": "cancelled",
  "pause_reason": null,
  "failure_reason": null,
  "audience": {
    "type": "list",
    "list_id": "lst_4Bd7fH0jL3nQ6sU9wZ2c"
  },
  "message": {
    "type": "template",
    "template": {
      "name": "order_update",
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "{{first_name}}"
            },
            {
              "type": "text",
              "text": "on its way"
            }
          ]
        }
      ]
    }
  },
  "merge_fallbacks": {
    "first_name": "there"
  },
  "require_opt_in": false,
  "consent_declared": true,
  "schedule": {
    "send_at": null,
    "timezone": "Asia/Dubai",
    "send_window": {
      "start": "09:00",
      "end": "20:00"
    },
    "recipient_timezone": true
  },
  "throttle_per_second": 20,
  "counters": {
    "total": 0,
    "queued": 0,
    "sent": 0,
    "delivered": 0,
    "read": 0,
    "failed": 0,
    "skipped": 0,
    "cancelled": 0,
    "skip_reasons": {}
  },
  "cost": {
    "currency": "USD",
    "estimated_wallet_micros": null,
    "estimated_credits": null,
    "wallet_micros": 0,
    "package_credits": 0
  },
  "created_at": "2026-10-05T09:00:00.000Z",
  "launched_at": null,
  "started_at": null,
  "paused_at": null,
  "completed_at": null,
  "cancelled_at": "2026-10-05T09:12:30.000Z"
}