ziett logo icon

Docs

HomeGet Started

Send Batch Campaign

POST

api.ziett.co/c/v1 /campaigns/batch

Initiate a high-throughput messaging campaign for multiple recipients. Instead of making hundreds of individual HTTP requests, this endpoint allows you to submit a batch payload. The system will process the list, validate numbers, and queue them for delivery asynchronously.

For sending a single time-sensitive alert (like an OTP), use Send Message instead.

How It Works

Because batch processing handles hundreds of numbers simultaneously, this endpoint operates entirely asynchronously to prevent HTTP timeouts.

  1. Creation — The API immediately accepts your payload and creates a campaign record with a PROCESSING status.
  2. Processing — Background workers parse the recipient list, format the numbers, calculate routing paths, and debit the total cost from your organization's billing account balance.
  3. Queueing — Individual message objects are generated and pushed to the provider specific delivery queues.
  4. Sending — Once all messages are successfully enqueued, the campaign status transitions to SENDING.
  5. Completion - Another system process will monitor the message delivery and mark the campaign as completed once all messages have been SENT.

202 Accepted is returned instantly after step 1. You should rely on webhooks to be notified when the campaign reaches the COMPLETED state or track its progress via the Retrieve Campaign endpoint.

Request

Required scope: apikey:campaign:send

Body

Content-Type: application/json

FieldTypeRequiredDescription
remitter_iduuid✅The approved Sender ID resource used to issue the campaign.

Rules: Must be a valid UUID v7.
contentstring✅The actual text content of the message. For SMS, long messages are split automatically.

Rules: Minimum 1, Maximum 10,000 characters.
channel_typeenum✅The communication channel used to deliver the batch.

Rules: Accepted values are SMS.
recipientsarray[string]✅List of destination phone numbers. Accepts local formats or international E.164 format.

Rules:
• Array length: 2 to 1000 items.
• Regex format per item: ^\+?[\d\s\-\.]{7,30}$
namestring❌Internal friendly name for the campaign to help you identify it in the dashboard.

Rules: Minimum 1, Maximum 200 characters.
country_alpha2string❌ISO Code 3166-1 alpha-2 specifying the default country if local numbers are passed without international prefixes (e.g., AO, PT).

Rules: Exactly 2 characters matching regex ^[A-Z]{2}$.

Examples

import httpx

response = httpx.post(
    "[https://api.ziett.co/c/v1/campaigns/batch](https://api.ziett.co/c/v1/campaigns/batch)",
    headers={
        "X-API-KEY": "zk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "name": "Black Friday Promo - Luanda",
        "remitter_id": "019b4b56-e704-7c30-83a0-527df63c3e00",
        "channel_type": "SMS",
        "country_alpha2": "AO",
        "content": "Flash Sale! Enjoy 50% off on all items this weekend only.",
        "recipients": [
            "+244990000001",
            "+244990000002",
            "990000003" # Will be parsed using country_alpha2 'AO'
        ]
    },
)

if response.status_code == 202:
    print("Batch accepted. Processing asynchronously.")
else:
    print(f"Error: {response.json()}")

Responses

202 Accepted — Campaign Queued

The payload schema is valid, and the campaign has been enqueued for background validation and processing.

{
  "message": "Campaign accepted and is pending processing.",
  "campaign_id": "019b4b56-e704-7c30-83a0-527df63c3e00"
}

(Note: Save the campaign_id returned to poll its status later or match it against incoming webhooks).

401 Unauthorized — Invalid API Key

The X-API-KEY header is missing, malformed, or the key has been revoked.

{
  "code": "AUTH_INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked.",
  "status": 401,
  "trace_id": "a1b2c3d4e5f644358a9e7011c123c831",
  "timestamp": "2026-05-14T10:30:00.000000+00:00",
  "service": "core"
}

402 Payment Required — Insufficient Funds

Your organization's credit balance is strictly below the estimated cost required to dispatch this batch. The campaign is immediately aborted.

{
  "code": "BILLING_INSUFFICIENT_FUNDS",
  "message": "Your account balance is too low to process this batch request. Please top up your credits.",
  "status": 402,
  "trace_id": "c109f78ae57744358a9e7011c123c831",
  "timestamp": "2026-05-14T10:30:00.000000+00:00",
  "service": "billing"
}

422 Unprocessable Entity — Validation Error

The request body failed to meet constraints (e.g., array contains more than 1,000 numbers, or an item fails the regex pattern).

{
  "code": "VALIDATION_ERROR",
  "message": "One or more fields failed validation.",
  "status": 422,
  "trace_id": "f812a3bc91e044358a9e7011c456d901",
  "timestamp": "2026-05-14T10:30:00.000000+00:00",
  "service": "core",
  "fields": {
    "recipients": "Ensure this value has at most 1000 items.",
    "country_alpha2": "String should match pattern '^[A-Z]{2}$'."
  }
}

Rate Limits

Due to the heavy database operations required to process batches, this endpoint is strictly limited to 10 requests per minute per API Key. Ensure your systems employ proper backoff strategies. See Rate Limits & Reliability.

Related Endpoints

  • Send Message — Dispatch a single transactional message instantly.
  • Get Campaign — Retrieve the execution status and analytics from a campaign.

List Messages

Retrieve a paginated list of all messages sent by your organization with advanced filtering.

Retrieve Campaign

Fetch the detailed status, metadata, configuration, and structural lifecycle metrics of a specific batch campaign.