Campaigns

Create, schedule, and monitor bulk messaging campaigns.

📄️List campaigns

Returns a paginated list of campaigns for your account. Use isDraft=true to see unpublished drafts that have not yet been confirmed, or isDraft=false to exclude them. Use isProgrammed=true to retrieve only campaigns that have been confirmed and are scheduled for future delivery. Filter by channel with sendingMode set to SMS, RCS, or WHATSAPP (comma-separated values are accepted to match multiple channels at once). The search parameter performs a case-insensitive match against campaign name and description fields. Use startDate and endDate (yyyy-MM-dd format) together to restrict results to campaigns created or scheduled within that date window. Results are paginated: page is 0-based and limit controls the page size. Use direction=ASC or direction=DESC to control sort order. The readyToSend filter lets you find campaigns that have been fully configured but not yet confirmed (true) or campaigns still being drafted (false). This endpoint is useful for building campaign dashboards and monitoring the overall state of your messaging operations. Returns 401 if the API key is missing or invalid.

📄️Create a campaign

Creates a new bulk messaging campaign. The typical lifecycle is: (1) Create the campaign with readyToSend=false to save it as a draft. (2) Optionally update the campaign with PUT /campaigns/{id} to adjust its configuration. (3) Call POST /campaigns/{id}/calculateGoal to compute the recipient count and estimated cost. (4) Review the price with GET /campaigns/{id}/price. (5) Set readyToSend=true via PUT /campaigns/{id} when the configuration is final. (6) Confirm and dispatch the campaign with PUT /campaigns/{id}/confirm. The channel is determined by the sendingMode field. Valid values are: SMS (plain text messages), RCS (rich card messages via an RCS agent), WHATSAPP (pre-approved WhatsApp templates), and combined modes like RCS_SMS, WHATSAPP_SMS, WHATSAPP_RCS, WHATSAPP_RCS_SMS which provide automatic fallback across channels. For SMS campaigns, you must provide smsSender (the alphanumeric sender ID or phone number) and smsBody (the message text, which supports {{placeholder}} syntax for personalization using contact fields). For RCS campaigns, you must provide rcsAgentId and rcsTemplateId. For WhatsApp campaigns, you must provide whatsappPhoneNumberId and whatsappTemplateId. Recipients are specified either by contactListIds (an array of contact list IDs, destinationType=1) or by destinations (an array of phone numbers in E.164 format, destinationType=2). You can set a scheduledDate in the future (format: yyyy-MM-dd HH:mm:ss.SSSZ) to schedule the campaign for later delivery instead of immediate dispatch upon confirmation. Returns 400 if required fields are missing or if sendingMode is not a valid value. Returns 401 if the API key is missing or invalid.

📄️Get campaign statistics

Returns aggregated delivery statistics for campaigns in a given date range. Results are grouped by the aggregateOn time bucket. Valid values for aggregateOn are: hour, day, week, and month. You must provide both startDate and endDate in yyyy-MM-dd format to define the reporting window. Filter by sendingMode (SMS, RCS, WHATSAPP) to see statistics for a specific channel, or omit it to get combined stats across all channels. Set isDraft=false to exclude draft campaigns that were never sent, so that only confirmed and dispatched campaigns contribute to the statistics. Each time bucket in the response contains counts for total messages sent, delivered, failed, and other delivery metrics. Results are paginated: use page (0-based) and limit to control pagination, and direction=ASC or direction=DESC to sort the time buckets chronologically or in reverse. This endpoint is useful for building analytics dashboards, generating periodic delivery reports, and monitoring campaign performance trends over time. Returns 401 if the API key is missing or invalid.

📄️Update a campaign

Updates the details of an existing campaign. Only campaigns that are still in draft status (status=0) or scheduled status (status=1) can be modified. Campaigns that are currently being sent (status=2), completed (status=3), or failed (status=4) cannot be updated. You can use this endpoint to change the campaign name, description, message body, sender, recipient contact lists, sending mode, scheduled date, or the readyToSend flag. A common workflow is to create a campaign as a draft (readyToSend=false), iterate on its configuration using this endpoint, then set readyToSend=true when the campaign is finalized, and finally call PUT /campaigns/{id}/confirm to dispatch it. After updating recipient lists or message content, call POST /campaigns/{id}/calculateGoal to refresh the recipient count and cost estimate. Returns 400 if the request body is invalid or if the campaign is in a non-editable state. Returns 404 if no campaign exists with the given ID under your account. Returns 401 if the API key is missing or invalid.

📄️Get a campaign

Returns the full details of a single campaign identified by its numeric ID. The response includes the campaign status, sending channel (sendingMode), recipient count (totalDestinations), delivery results (totalSuccess, totalFailed), message content (smsBody for SMS, template IDs for RCS or WhatsApp), the list of associated contactListIds, and any scheduled date. Use this endpoint to inspect a campaign at any stage of its lifecycle: while drafting, after confirmation, during sending, or after completion. The status field is numeric: 0 means draft, 1 means ready/scheduled, 2 means sending in progress, 3 means completed, and 4 means failed. Returns 404 if no campaign exists with the given ID under your account. Returns 401 if the API key is missing or invalid.

📄️Delete a campaign

Permanently deletes a campaign. Only campaigns that are still in draft status (status=0) or scheduled status (status=1) can be deleted. Campaigns that are currently being sent (status=2), already completed (status=3), or in a failed state (status=4) cannot be deleted because their delivery records must be preserved for reporting. If you need to stop a scheduled campaign before it sends, delete it before the scheduledDate is reached. This operation is irreversible: once deleted, the campaign and its configuration are permanently removed and cannot be recovered. Returns 204 No Content on successful deletion. Returns 404 if no campaign exists with the given ID under your account, or if the campaign is in a non-deletable state. Returns 401 if the API key is missing or invalid.

📄️Recalculate campaign cost

Recalculates the estimated recipient count and total cost for the campaign based on its current configuration and the associated contact lists. You should call this endpoint every time you modify the campaign recipients (contactListIds or destinations) or change the sendingMode, because different channels have different per-message pricing and the recipient count may change if lists are added or removed. The response includes the updated campaign object with recalculated totalDestinations and cost fields. This is a prerequisite step before confirming a campaign: if you skip it, the confirm endpoint may reject the campaign because the cost has not been computed. After calling this, use GET /campaigns/{id}/price to retrieve just the price breakdown. Returns 404 if no campaign exists with the given ID under your account. Returns 401 if the API key is missing or invalid.

📄️Confirm / schedule a campaign

Validates and confirms the campaign for sending. This is the final and irreversible step in the campaign lifecycle: once confirmed, messages will be dispatched to all recipients (either immediately or at the scheduledDate if one was set). Before calling this endpoint, ensure that: (1) The campaign has a valid sendingMode and the corresponding channel-specific fields are populated (smsSender/smsBody for SMS, rcsAgentId/rcsTemplateId for RCS, whatsappPhoneNumberId/whatsappTemplateId for WhatsApp). (2) At least one recipient source is configured (contactListIds or destinations). (3) The campaign cost has been calculated by calling POST /campaigns/{id}/calculateGoal. (4) Your account has sufficient credit to cover the total cost. (5) The readyToSend flag is set to true on the campaign. Returns 202 Accepted when the campaign is successfully confirmed and queued for delivery. Returns 400 if any validation fails: missing required fields, insufficient credit balance, readyToSend is false, or the cost has not been calculated. Returns 404 if no campaign exists with the given ID under your account. Returns 401 if the API key is missing or invalid.

📄️Get campaign total price

Returns the estimated total price for the campaign based on its current configuration. The price depends on the sendingMode (channel), the number of recipients in the associated contact lists, and the per-message rate for your account. You should call POST /campaigns/{id}/calculateGoal before using this endpoint to ensure the cost estimate is up to date. If the cost has not been calculated yet, the returned price may be zero or stale. Use this endpoint to display a cost preview to users before they confirm and dispatch the campaign with PUT /campaigns/{id}/confirm. Returns 404 if no campaign exists with the given ID under your account. Returns 401 if the API key is missing or invalid.