Quick start

Create an API key and send your first SMS. It takes a few minutes once you have an approved sender ID.

Before you start

  • A Kpododo account with credit on its balance. Every message is charged, see message parts and pricing.
  • An approved sender ID, the name your message comes from. Requesting one usually takes about 48 hours, so start early. See sender IDs.

1. Create an API key

  1. In the dashboard, open Account > Developer.
  2. Under API keys, choose Create key, name it and pick Live or Test.
  3. Copy the key. It is shown once.

Keep it in an environment variable rather than in your code:

Shell
export KPODODO_API_KEY="kp_live_..."

2. Send an SMS

POST /v1/sms needs an Idempotency-Key header: a unique string you choose, such as a UUID. If the request times out and you send it again with the same key, you get the original response back and nothing is sent or charged twice. See idempotency.

curl https://api.kpododo.com/v1/sms \
  -H "Authorization: Bearer $KPODODO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "MyShop",
    "to": ["0244000111", "+233200000002"],
    "text": "Your order 1043 has shipped.",
    "reference": "order-1043"
  }'

from is your sender ID, to is a list of 1 to 1000 phone numbers in any common Ghana format (see phone number formats), and text is the message. reference is optional: your own label of up to 100 characters, returned in responses and webhooks.

3. Read the response

A message sent now returns 200 straight away, before delivery:

Response
{
  "id": "6f1c2a9e-1b7d-4c55-9a51-3f0a9d2c8b11",
  "object": "sms",
  "status": "queued",
  "from": "MyShop",
  "text": "Your order 1043 has shipped.",
  "reference": "order-1043",
  "encoding": "GSM-7",
  "parts": 1,
  "recipients_count": 2,
  "cost": "0.0500",
  "currency": "GHS",
  "charged": true,
  "schedule_at": null,
  "created_at": "2026-11-01T10:15:00Z",
  "counts": {
    "queued": 1, "sent": 0, "delivered": 0, "failed": 0, "rejected": 0,
    "expired": 0, "unconfirmed": 0, "skipped": 1, "scheduled": 0
  },
  "recipients": [
    { "id": "b0c4...", "to": "+233244000111", "status": "queued", "parts": 1, "cost": "0.0500" },
    { "id": null, "to": "+233200000002", "status": "skipped", "skip_reason": "do_not_call", "parts": 0, "cost": "0.0000" }
  ]
}
  • id identifies the message. Keep it to check delivery later.
  • cost is what was charged up front from your balance, in currency.
  • The second number is on this account's Do-Not-Call list, so it was skipped: not sent and not charged.

4. Check delivery

Fetch the message to see live statuses for each recipient, or register a webhook to be told when each one is delivered.

curl https://api.kpododo.com/v1/sms/6f1c2a9e-1b7d-4c55-9a51-3f0a9d2c8b11 \
  -H "Authorization: Bearer $KPODODO_API_KEY"

Sending later

Add schedule_at with an RFC 3339 time at least 1 minute and at most 90 days ahead, for example "2026-11-02T09:00:00Z". The response then has status: "scheduled" and charged: false, and cost is an estimate at today's rate. Nothing is charged until the message is sent.

Next steps