Subscription premium SMS lets you send paid content to people who have opted in to your service — daily tips, devotionals, market prices — on a daily, weekly or monthly cadence. Each message is charged to the subscriber’s airtime when it is delivered, until they opt out.

• How the subscription flow works
• Send a premium message: request
• Send a premium message: response
• Sample send-message request
• Add or remove a subscriber
• Let Sozuri send on a schedule
• Subscriber webhooks (activation, deactivation, consent, delivery)
• Error responses

How the subscription flow works

1. A subscriber opts in by texting your activation keyword (e.g. JOIN) to your shortcode — or you ask for them with the subscribe endpoint, and the network asks them to confirm on their phone.
2. Sozuri sends an activation webhook when the network confirms the subscription (and a consent webhook with their answer, when they were asked to confirm). From then on the number is an active subscriber.
3. You send premium content through the API, or let Sozuri send it on a schedule. Only active subscribers can be sent to, and each message is charged.
4. Delivery reports and opt-outs arrive as webhooks.

Send a premium message: request parameters

Authentication and headers

Send your project API key as a Bearer token — or as an apiKey field in the body or query string — and your project’s name in the project field. The key alone does not authenticate, and an apiKey header is not read. Every endpoint on this page accepts POST (JSON or form body) and GET (query string).

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

Send at least one of premium_id, keyword or from; they are tried in that order. Do not send a linkId on a subscription message — on a shortcode that also carries an on-demand service, a linkId selects the on-demand one. One request sends one message to one subscriber.

Send a premium message: response

The request is answered once the network has accepted or refused the message, so allow a few seconds. An accepted message returns HTTP 200 with:

Sample request

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

{
    "project": "my project",
    "number": "254700000001",
    "message": "Today's quote: The best way out is always through. - Robert Frost.",
    "keyword": "JOIN",
    "from": "20000"
}

Sample JSON response

{
    "messageData": { "messages": 1 },
    "recipients": [
        {
            "messageId": "SOZPREM0123456789ABC",
            "to": "254700000001",
            "status": "accepted",
            "statusCode": "11",
            "messagePart": 1,
            "keyword": "JOIN",
            "type": "subscription",
            "linkId": null
        }
    ]
}

Add or remove a subscriber

Subscribers normally opt in themselves by texting your activation keyword to your shortcode. You can also request a subscription 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 and unsubscribe fields

Subscribe

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

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

statusCode and description are the network’s own reference and wording for the request. Keep them for your records; act on the webhooks, not on these.

Unsubscribe

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

{
    "project": "my project",
    "shortcode": "20000",
    "keyword": "JOIN",
    "number": "254700000001",
    "network": "safaricom",
    "type": "unsubscribe",
    "status": "inactive",
    "statusCode": "1",
    "description": "Subscription cancelled"
}

As soon as the network accepts the cancellation, the number is inactive in Sozuri and can no longer be sent to. If the network refuses it, the number stays active and you get the refusal back. A number that is still Pending is not active yet, so unsubscribing it answers Subscriber is already Inactive.

A subscriber can also opt out by texting your opt-out keyword (usually STOP) to your shortcode, and the network can deactivate them — for example when an offer is withdrawn. Both produce a deactivation webhook.

Let Sozuri send on a schedule

You do not need your own cron job or content system. On the Premium Services page, 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 five-field cron expression, in the timezone you choose (Nairobi by default).
• What gets sent — either one fixed message, or a list with one message per line. A list is sent in order, one line per run, starting again from the top after the last line. The message box holds up to 480 characters in total, list included.
• The price per 160-character part, charged to the subscriber.

Placeholders {name}, {msisdn}, {date}, {time}, {offer} and {shortcode} are filled in per recipient; {name} becomes “there” when we have no name for the subscriber. Every message sent appears in the Message log on the same page, grouped by a run id, and each raises a delivery webhook exactly as an API send does.

Subscriber webhooks

You receive four kinds of webhook, all POSTed to the callback URL on your premium service. That URL is shown as Callback on the service’s card on the Premium Services page. We set it when the service is provisioned — send it to support to set or change it. It is not one of the URLs under Manage API › Callback URLs, which are for ordinary SMS.

1. Activation

Sent when the network reports the subscription is live — whether the subscriber texted your keyword or confirmed after a subscribe call.

{
    "project": "my project",
    "shortcode": "20000",
    "keyword": "JOIN",
    "number": "254700000001",
    "network": "safaricom",
    "type": "activation",
    "status": "active",
    "authKey": "szk_YOUR_AUTH_KEY"
}

2. Deactivation

Sent when the network reports an opt-out — the subscriber texted your opt-out keyword, or the network deactivated them.

{
    "project": "my project",
    "shortcode": "20000",
    "keyword": "JOIN",
    "number": "254700000001",
    "network": "safaricom",
    "type": "deactivation",
    "status": "inactive",
    "authKey": "szk_YOUR_AUTH_KEY"
}

3. Consent

Sent when the subscriber answers the network’s confirmation prompt — typically after you called subscribe. status is active if they accepted and inactive if they declined.

{
    "project": "my project",
    "shortcode": "20000",
    "keyword": "JOIN",
    "number": "254700000001",
    "network": "safaricom",
    "type": "consent",
    "status": "inactive",
    "authKey": "szk_YOUR_AUTH_KEY"
}

4. Delivery status

Sent once for each delivery report the network sends for one of your premium messages.

{
    "project": "my project",
    "shortcode": "20000",
    "keyword": "JOIN",
    "number": "254700000001",
    "messageId": "SOZPREM0123456789ABC",
    "network": "safaricom",
    "type": "premiumDelivery",
    "status": "DeliveryToTerminal",
    "timestamp": 1762560000,
    "authKey": "szk_YOUR_AUTH_KEY"
}

messageId is the recipients[].messageId the send returned. status is the network’s own delivery description, passed through as written: DeliveryToTerminal means delivered; a description that mentions an absent subscriber, expiry or delivery being impossible means it was not. timestamp is the Unix time, in seconds, when Sozuri sent the webhook.

How webhooks are sent and verified

POST https://your-app.example/sozuri/premium
Content-Type: application/json
Accept: application/json
X-Sozuri-Signature: t=1762560000,v1=<hex hmac_sha256(signing_secret, "1762560000." + raw_body)>

• Authentication. The body ends with your project’s authKey, and the X-Sozuri-Signature header signs the exact raw body. Both come from Manage API › Callback URLs › Webhook security, which appears once your project has a callback configuration. Without one, premium webhooks are sent with neither. See Verifying authenticity.
• Several URLs. The callback may be a comma-separated list; each URL gets its own copy.
• Enforce HTTPS. If it is ticked on your callback configuration, a plain http:// callback is not called at all.
• One attempt. Each webhook is sent once. We wait up to 8 seconds, do not follow redirects and do not retry, so answer quickly with a 2xx.

Error responses

A refused request answers HTTP 200 with { "status": "error", "description": "…" }, so check status, not the HTTP code.

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

{
    "error_code": "VALIDATION_FAILED",
    "message": "The submitted data failed validation.",
    "retryable": false,
    "errors": { "keyword": ["The keyword field is required."] }
}

{
    "error_code": "AUTHENTICATION_FAILED",
    "message": "Authentication failed. Check your API key or bearer token.",
    "retryable": false
}