Subscription premium SMS lets you bill subscribers on a recurring schedule — daily, weekly or monthly — for content delivered to their phone. Customers opt in via your shortcode, and the carrier charges them automatically until they opt out.

• How the subscription flow works
• Send a premium message: request
• Send a premium message: response
• Sample send-message request
• Activate or deactivate a subscriber
• Subscriber webhooks (activate, deactivate, consent, delivery)
• Error responses

How the subscription flow works

1. A subscriber opts in by texting your keyword (e.g. JOIN) to your shortcode — or you call the activate endpoint on their behalf with explicit consent.
2. Sozuri pushes an activation webhook with the subscriber’s number and the keyword they used.
3. You send recurring premium content via the API. Each message triggers a charge.
4. Delivery and unsubscribe events stream to your webhook as they happen.

Send a premium message: request parameters

Required headers

POST /api/v1/messaging/sendpremium HTTP/1.1
Host: sozuri.net
Authorization: Bearer Your_Project_API_KEY
Content-Type: application/json
Accept: application/json

Send a premium message: response

Sample request

POST /api/v1/messaging/sendpremium HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf.......R9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/json

{
    "project": "my project",
    "from": "23546",
    "number": "2547251642xx",
    "campaign": "Daily Quote",
    "channel": "premium",
    "message": "Today's quote: The best way out is always through. - Robert Frost.",
    "type": "subscription",
    "keyword": "Omoka"
}

Sample JSON response

{
    "messageData": { "messages": 1 },
    "recipients": [
        {
            "messageId": "MSGBLK6012A7E8B90A21611835368",
            "to": "2547251642xx",
            "status": "accepted",
            "statusCode": "11",
            "messagePart": 1,
            "type": "subscription"
        }
    ]
}

Add or remove a subscriber

Subscribers normally opt in themselves by texting your activation keyword to your shortcode. You can also add one yourself — for example when somebody opts in on a web form — using the subscribe endpoint. These are separate endpoints from sending, not a type on the send call.

Subscribe

curl -X POST https://sozuri.net/api/v1/messaging/subscribe \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer Your_Project_API_KEY' \
    -d '{
        "project": "my project",
        "keyword": "JOIN",
        "number": "0722503129",
        "name": "Jane Doe"
    }'

{
    "project": "my project",
    "shortcode": "20555",
    "keyword": "JOIN",
    "number": "254722503129",
    "network": "safaricom",
    "type": "subscribe",
    "status": "pending",
    "statusCode": "112",
    "description": "Your request for the service is under process."
}

Unsubscribe

curl -X POST https://sozuri.net/api/v1/messaging/unsubscribe \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer Your_Project_API_KEY' \
    -d '{
        "project": "my project",
        "keyword": "JOIN",
        "number": "0722503129"
    }'

A subscriber can also opt out themselves by texting your deactivation keyword (usually STOP) to your shortcode, and the carrier can deactivate them — for churn, or when an offer is withdrawn. All three routes produce a deactivation webhook.

Let Sozuri send on a schedule

You do not need your own cron job or content system. On Premium Services in your dashboard, a subscription service has a Sending schedule panel where you set:

• A cadence — every day at 07:00, weekdays, Mondays, the 1st of the month, or any cron expression, evaluated in your own timezone.
• What gets sent — either one fixed message, or a list with one message per line. A list is sent in order, one per run, and where it got to is remembered: paste 90 tips once and send one a day for three months.
• The price per message, charged to the subscriber.

Placeholders {name}, {msisdn}, {date}, {time}, {offer} and {shortcode} are substituted per recipient. Every send appears in your outbox with a run id, and each one raises a delivery webhook exactly as an API send does.

Subscriber webhooks

You’ll receive four kinds of asynchronous webhooks. Configure the receiving URL from Manage API › Callback URLs.

1. Activation

Fires when a subscriber opts in — either by texting your keyword to your shortcode, or after a successful activate API call.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "activation",
    "status": "success",
    "timestamp": "1603713484"
}

2. Deactivation

Fires when a subscriber opts out — via your STOP keyword, USSD menu or carrier dashboard.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "deactivation",
    "status": "success",
    "timestamp": "1603713484"
}

3. Consent

Fires after you call the activate API. Status is success if the carrier accepted the activation, or failure if the subscriber rejected the consent prompt.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "consent",
    "status": "failure",
    "timestamp": "1603713484"
}

4. Delivery status

Fires for each premium message you sent — one event per state change.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "premiumDelivery",
    "status": "success",
    "timestamp": "1603713484"
}

Optional callback authentication

Your project’s Auth Key is included in every callback body as authKey, alongside an X-Sozuri-Signature HMAC header, so you can verify a webhook is genuinely from Sozuri. Both live under Manage API › Callback URLs › Webhook security — see Verifying authenticity.

Error responses

Subscription premium SMS uses the SDP error envelope: { "status": "error", "description": "…" }. Auth errors (Unknown project.) follow the SMS envelope and are documented on the Authentication page.

{
    "status": "error",
    "description": "Subscriber already Exists"
}

{
    "status": "error",
    "description": "Unknown Subscriber"
}

{
    "status": "error",
    "description": "Subscriber is already Inactive"
}

{
    "status": "error",
    "description": "Unknown, Expired, or Inactive Premium Service"
}

{
    "status": "error",
    "description": "Unsupported Number"
}