Sender IDs
The name a recipient sees as the sender of your SMS. You need at least one approved sender ID before the API will send a message.
Why you need one
Mobile network operators in Ghana only deliver SMS from sender names they have approved for a specific business. Each sender ID is reviewed by the network operator and registered to your account, and the from field of POST /v1/sms must be one of yours. The match ignores case, and the registered spelling is used on the message.
Platform names such as Kpododo, and names made to look like them (for example KP0D0D0), are reserved and cannot be requested.
How to request one
Request sender IDs in the dashboard under Account > Sender IDs > Request. There is no API for this step. You will be asked for:
- the name: 3 to 11 characters of letters, digits and single spaces, with at least one letter (spaces count towards the 11);
- what you will send, and a sample message;
- the business name and a contact;
- supporting documents: your business registration certificate and a letter of authorisation.
The network operator reviews the request. This usually takes about 48 hours.
Statuses
| Status | Meaning |
|---|---|
pending | We have received the request and have not yet sent it to the network operator. |
submitted | With the network operator for review, typically about 48 hours. |
approved | Approved. Check usable before sending: it may still be activating on the network for a few minutes. |
rejected | Not approved. rejection_reason says why. You can request again. |
revoked | No longer usable. Request again if you need it. |
cancelled | The request was cancelled. Request again if you need it. |
Check which sender IDs you can use
GET /v1/sender-ids lists every sender ID on your account. Use the usable field to decide: it is true only when the sender ID is approved and active on the network (ready_to_send). An approved sender ID that is not yet ready is still being activated, which takes minutes.
curl https://api.kpododo.com/v1/sender-ids \
-H "Authorization: Bearer $KPODODO_API_KEY"{
"data": [
{
"id": "uuid",
"name": "MyShop",
"status": "approved",
"usable": true,
"ready_to_send": true,
"rejection_reason": null,
"created_at": "...",
"approved_at": "..."
},
{
"id": "uuid",
"name": "MyShopGH",
"status": "submitted",
"usable": false,
"ready_to_send": false,
"rejection_reason": null,
"created_at": "...",
"approved_at": null
}
]
}Sender errors
When POST /v1/sms refuses a sender, nothing is sent or charged. Branch on code:
| HTTP | Code | What it means | What to do |
|---|---|---|---|
| 400 | SENDER_REQUIRED | The from field is empty. | Pass one of your sender IDs. |
| 403 | SENDER_NOT_OWNED | The name is not registered to your account, or it is a reserved platform name or look-alike. | Request your own sender ID. |
| 403 | SENDER_NOT_APPROVED | It is yours, but pending, submitted, rejected, revoked or cancelled. | Wait for approval, or request again. |
| 403 | SENDER_NOT_READY | Approved, but still being activated on the network. | Retry in a few minutes. |