Quickstart

Get a key, send a message, and confirm delivery, in about five minutes.

1. Get your API key

Create an account in the dashboard, then open API keys and create one. The full key is shown once, so copy it somewhere safe.

2. Top up and set a sender ID

Add credit with M-Pesa from the dashboard, and make sure you have an active sender ID (your brand name). A test send needs both. See Sender IDs if you do not have one yet.

3. Send a message

Use the SDK, or call the API directly. Both do the same thing.

Install the SDK

npm install @pesarails/sms

send.ts

import { Pesarails } from "@pesarails/sms";

const sms = new Pesarails(process.env.PESARAILS_KEY);

const res = await sms.send({
  to: "254712345678",
  sender: "PESARAILS",
  message: "Hello from PESA RAILS",
});

console.log(res.id, res.status); // "a1b2c3" "sent"

PHP

<?php
$ch = curl_init("https://api.sms.pesarails.com/v1/messages");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("PESARAILS_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "to" => "254712345678",
    "sender" => "PESARAILS",
    "message" => "Hello from PESA RAILS",
  ]),
]);
echo curl_exec($ch);

Python

import os, requests

requests.post(
    "https://api.sms.pesarails.com/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['PESARAILS_KEY']}"},
    json={
        "to": "254712345678",
        "sender": "PESARAILS",
        "message": "Hello from PESA RAILS",
    },
)

4. Read the response

A successful send returns the message id, status and the credit left on your account.

200 OK

{
  "message": {
    "id": "a1b2c3",
    "status": "sent",
    "to": "254712345678",
    "sender": "PESARAILS",
    "segments": 1,
    "priceKes": 0.5,
    "balanceAfter": 499.5
  }
}

Tip

Want to know when it is delivered to the handset? Register a delivery-report webhook and we will post you the status in real time.