Sendd API (0.1.0)

Validates, prices and pays for the message in one step, then returns 202 Accepted: the sender is checked, segments are counted (GSM-7 / UCS-2, at most 10), the price comes from the organization's current rates, and the total is held from the wallet. If any check fails, nothing is recorded or held. Dispatch to the provider happens asynchronously; accepted is not delivered.

Idempotency. X-Idempotency-Key is required. Keys are scoped to tenant, operation and request fingerprint. Repeating a key with an identical body returns the original response (header X-Idempotent-Replay: true) and creates no second message or charge. Repeating a key with a different body returns 409 idempotency_conflict.

Test-mode keys never send to a provider and are never charged (test: true, price.charged: false). Their messages complete at once with a scripted outcome by the recipient's last digit: 1 or 2 failed, 8 undelivered, anything else delivered. In local development and whenever live dispatch is disabled, no real SMS leaves the platform.

Limits: live and test traffic are limited separately per organization, and one recipient can receive a bounded number of live messages an hour (429 rate_limited, with Retry-After).

Promotional messages (traffic_class: promotional) go only to a number with a contact whose consent is recorded (422 consent_required, field to) and no active opt-out (422 recipient_opted_out, field to). Transactional messages are never refused for either (provisional). A promotional message accepted while the sending window is closed (GET /v1/sending-window) stays queued, unsent and uncharged, until the window opens (the response's held_until); if it expires first it is expired and its hold released. It is accepted, not refused.

The SMS route decides which characters a message may hold and how it is counted (GET /v1/service-status gives sms_route). On gsm0338 any text is sent, as GSM-7 or, with a character outside GSM 03.38, as UCS-2. On ascii the body must be printable ASCII plus newline (no carriage return); every character counts one, 160 for one segment, then 153 per segment. A body with any other character (accented letters, curly quotes, dashes, emoji, £) is refused with 422 encoding_not_supported (field body), whose details list the characters and their positions. Sendd never removes or replaces characters: change the text and send again.

Refusals: 403 sender_not_authorized (field from), 403 organization_not_verified, 403 wallet_frozen, 409 no_price_plan, 422 insufficient_funds, 422 too_many_segments, 422 encoding_not_supported, 422 consent_required, 422 recipient_opted_out, 422 validation_failed, 422 sender_not_ready (field from: Sendd approved the sender ID, but the SMS route has not approved it yet; see the sender ID's provider_approval).

Single messages and campaign messages together, unless campaign narrows the list. A campaign message's to is masked (+25575****01) unless the caller is a member who may read contacts (contacts.read); API keys always see campaign numbers masked.

A draft holds the name, traffic class, sender ID, one body for every recipient (no personalization) and the contact groups. Nothing is sent, priced or held: quote it next (POST /v1/campaigns/{id}/quote). Launching (POST /v1/campaigns/{id}/launch) needs a signed-in member.

Idempotency. X-Idempotency-Key is required: the same key with the same draft returns the original (200, header X-Idempotent-Replay: true), so a double click creates one draft; the same key with a different draft is 409 idempotency_conflict.

Test-mode keys cannot create campaigns (403 test_mode_not_allowed). Session callers also send X-CSRF-Token. At most 100 drafts (409 too_many_drafts; discard one) and 50 groups per campaign. The body is checked as for single messages (at most 10 segments: 422 too_many_segments). Refusals: 422 validation_failed (with field), 403 forbidden.

Only a draft can change (409 campaign_not_draft). Send only the fields to change; scheduled_at and validity_seconds can be cleared with null. Every change bumps version and drops the draft's quote and audience snapshot: quote again before launching. Send version to refuse a change to a draft that changed since you loaded it (409 campaign_changed); without it, the change applies to the draft as it is now. Test-mode keys are refused (403 test_mode_not_allowed); session callers also send X-CSRF-Token.

Every recipient of the campaign's frozen audience, in audience order (n), with its message once one was queued. status is the message's public status once the recipient was fed (accepted, submitted, delivered, undelivered, failed, unknown, cancelled); before that, the recipient's own: pending (its share still held), skipped_opted_out or skipped_no_consent (skipped when it was due, share released), expired (the campaign expired before it was sent) or cancelled (cancelled before it was sent). submitted is the provider's acceptance, not delivery. charge is where the recipient's share of the reservation is now: held, captured (the provider accepted the message) or released (back in the wallet).

Numbers are shown in full only to members who may read contacts (contacts.read); API keys and other callers see them masked (+25575****01, numbers_masked: true) and cannot search (403 forbidden, field search). search is the start of a number (0754, +255 754, 754). A draft has no recipients to show (409 campaign_not_launched). A read that takes too long answers 503 read_timeout: retry, or narrow it.

The recipients of GET /v1/campaigns/{id}/messages as one CSV file (UTF-8, comma-separated, with a header line), in audience order: recipient (n), phone, status, failure_reason, segments, unit_price_cents, amount_cents (the recipient's share), charge (held, captured or released), queued_at_eat, updated_at_eat, final_at_eat (Africa/Dar_es_Salaam, with the +03:00 offset) and message_id. Numbers are in full only for members who may read contacts, masked otherwise, as in the list.

A value whose first character, after any leading spaces, control or format characters, is =, +, -, @, |, a tab, a carriage return, a line feed or a full-width ＝ ＋ － ＠ gets a leading apostrophe, so a spreadsheet never runs it as a formula (every phone number starts with '+255). The file is read from the database a page at a time while it is sent; if a read fails midway, the connection is broken rather than the file ending short. At most 500,000 rows per file (422 export_too_large: export one status at a time); exports are limited per organization (429 rate_limited) and each one is audited.

In one step, the database freezes the audience and prices it:

• one recipient per distinct number of the draft's groups (a contact in several groups counts once: audience.duplicates);
• numbers with an active opt-out are skipped (audience.opted_out), whatever the class;
• for promotional campaigns, contacts without a consent record are skipped (audience.no_consent);
• segments are counted from the body, and the price comes from the organization's current rates: total = unit_amount × segments × audience.eligible (cents).

The consent and opt-out rules are provisional product defaults. The quote is immutable and valid for 15 minutes; a later rate change never alters it. Quoting again rebuilds the audience; editing the draft drops it. Nothing is held from the wallet until launch. assumptions lists the caveats that apply to every quote, as codes.

Idempotency. X-Idempotency-Key is required: the same key for the same campaign returns the original quote (200, X-Idempotent-Replay: true), whose status may since have become stale (the draft changed, lost a group, or was quoted again) or expired; the same key for another campaign is 409.

Refusals: 409 campaign_not_draft, 409 campaign_changed, 422 audience_empty (nobody eligible, or no groups), 422 audience_too_large (over 1,000,000 numbers or 2,000,000 group memberships), 422 total_too_large, 403 sender_not_authorized (field sender_id: the sender is not approved for the class), 409 no_price_plan, 422 too_many_segments, 422 encoding_not_supported (the body has characters the SMS route cannot send: see POST /v1/messages), 403 test_mode_not_allowed, 503 quote_timeout. A quote prices the campaign on the SMS route it was made on; once the route changes, it is stale. Deleting one of the draft's groups takes it out of the draft and drops its quote (the draft's version moves on). Session callers also send X-CSRF-Token.

The draft becomes discarded: it is kept for the record, its audience is deleted, and it no longer counts toward the 100-draft limit. Discarding a discarded campaign returns it unchanged (header X-Idempotent-Replay: true). A launched campaign is 409 campaign_not_draft (cancel it instead). Test-mode keys are refused; session callers also send X-CSRF-Token.

Launching holds the quote's total from the wallet in one step (a single reservation for the whole campaign) and the campaign becomes scheduled (with scheduled_at) or sending. Name the quote you reviewed: it must be the draft's latest quote, for the draft as it is now (409 quote_stale otherwise: the draft changed, lost a group, or was quoted again, or the SMS route changed since) and unexpired (409 quote_expired: quote again). A body the SMS route cannot send is 422 encoding_not_supported. The quote is honoured: a rate change after it does not change the price. Each message then draws its share (unit_amount × segments): charged when the provider accepts it, released when it fails, expires or is cancelled. Recipients who opt out (or, for promotional campaigns, lose their consent record) after the quote are skipped when their turn comes, and their share is released (provisional consent rules).

Refusals change nothing and keep the draft: 422 insufficient_funds (add credit and launch again), 403 wallet_frozen, 403 organization_not_verified, 403 sender_not_authorized, 422 sender_not_ready (field sender_id: the SMS route has not approved the sender ID yet), 422 schedule_out_of_range (start now or within 30 days; validity 1 to 72 hours), 422 outside_sending_window (a promotional campaign's start, now or scheduled, must fall inside the sending window: GET /v1/sending-window), 409 campaign_not_draft (it was launched or discarded already).

Sending window (promotional only; provisional): a promotional campaign is fed and sent only inside the window. When the window closes, its unsent messages are held, unsent and uncharged, until it opens again; what is still unsent at the campaign's expiry (validity_seconds after the start) expires and its share is released. Transactional campaigns have no window.

Idempotency. X-Idempotency-Key is required: the same key with the same request returns the original (200, X-Idempotent-Replay: true); with another request, 409 idempotency_conflict. A campaign is launched once, whatever the key. API keys cannot launch (until spending caps exist). Session callers send X-CSRF-Token.

Stops a scheduled or sending campaign: it becomes cancelling, the share of every recipient not yet queued is released at once, and its queued messages are cancelled (status cancelled, their share released) within moments; then it is cancelled. Messages already with the provider (sending, submitted, unknown) are not recalled: a send that began a moment before the cancel is sent and charged. cancel reports what the cancel found. Cancelling again returns the original (X-Idempotent-Replay: true); no idempotency key is needed. A draft, discarded or completed campaign is 409 campaign_not_cancellable. Session callers send X-CSRF-Token.

Promotional traffic is dispatched only between opens and closes each day, in time_zone (Africa/Dar_es_Salaam, EAT, UTC+3). A promotional campaign must start inside the window (422 outside_sending_window at launch), and promotional messages, from campaigns or single sends, are held while it is closed (never sent, never charged), then sent when it opens, unless they expire first. Transactional traffic has no window. The window is one platform setting: a provisional product default (08:00 to 20:00), not a statement of law (provisional).

Session-only; an API key cannot reach contacts. Filter by the start of a number or by group.

The number is normalized to +255…; one contact per number (409 contact_exists, field phone). consent records that the person agreed to receive messages and how (the note); promotional messages go only to contacts with a consent record and no active opt-out. A consent record is never overwritten. The consent rules are provisional product defaults, not legal advice.

name: a string sets it, null or an empty string clears it, absent leaves it. consent records consent when none is recorded; an existing record is kept as it is. The number never changes: delete the contact and add the new number.

The consent history and any opt-out of the number are kept; they belong to the number.

Names are unique per organization, ignoring case (409 group_name_taken); at most 500 groups (409 too_many_groups).

Contacts already in the group are left as they are. Every id must be one of the organization's contacts.

Contacts not in the group are ignored.

An active opt-out blocks every promotional message to the number (422 recipient_opted_out on POST /v1/messages), never a transactional one. It is kept per number, so it outlives the contact. Recording a number that is already opted out returns the active opt-out with 200 and created: false. Sendd adds no opt-out wording to messages and has no inbound STOP keyword yet (provisional).