Quickstart

Before you start

Examples use $SENDD_API_URL for the API address and $SENDD_API_KEY for your key. The public API address is announced at launch.

Everything here works with a test key: test messages never reach a phone and are never charged.

1. Create a test API key

Sign in, open Developers, and create a key with mode test and the scopes messages:send and messages:read. The secret (sndd_test_...) is shown once: keep it in your secret store, never in source code.

2. Check the key

GET /v1/key answers with the key's organization, mode and scopes. Any valid key may call it.

curl "$SENDD_API_URL/v1/key" \
  -H "Authorization: Bearer $SENDD_API_KEY"

3. Send a message

POST /v1/messages with an X-Idempotency-Key. from must be a sender ID your organization may use (GET /v1/sender-ids).

The answer is 202 Accepted with the status accepted: Sendd recorded the message and held its price. It is not delivered yet.

curl -X POST "$SENDD_API_URL/v1/messages" \
  -H "Authorization: Bearer $SENDD_API_KEY" \
  -H "X-Idempotency-Key: order-1042-ready" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+255712345678",
    "from": "SENDD",
    "body": "Your order #1042 is ready for pickup.",
    "client_ref": "order-1042-ready"
  }'

4. Follow its status

GET /v1/messages/{id} returns the current status. Instead of polling, register a webhook endpoint and Sendd tells you when the status changes.

curl "$SENDD_API_URL/v1/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $SENDD_API_KEY"

5. Go live

Live keys (sndd_live_...) need an organization Sendd has verified, funds in the wallet and an approved sender ID. A live message's price is held from the wallet when it is accepted.