Quickstart

Send your first message in the sandbox in about five minutes. Nothing is delivered to a real phone and no SMS units are used.

1. Create a test key

1. Log in to app.cloudmetis.com as an organisation admin.
2. Go to Management → Developer API and click Create key.
3. Choose Test (sandbox), give it a name and click Create key.
4. Copy the key (cm_test_…) and the webhook secret (whsec_…). They are shown only once.

2. Check the key works

curl https://api.cloudmetis.com/v1/sms/balance \
  -H "Authorization: Bearer cm_test_your_key"

{"units_available": 1000, "sandbox": true}

3. Send a message

cURL

curl -X POST https://api.cloudmetis.com/v1/sms/send \
-H "Authorization: Bearer cm_test_your_key" \
-H "Content-Type: application/json" \
-d '{"to": "0712345678", "message": "Your order #1042 has shipped."}'

PHP

$ch = curl_init('https://api.cloudmetis.com/v1/sms/send');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
      'Authorization: Bearer ' . getenv('CLOUDMETIS_API_KEY'),
      'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'to' => '0712345678',
      'message' => 'Your order #1042 has shipped.',
  ]),
]);
$response = json_decode(curl_exec($ch), true);
echo $response['message_id'];

Python

import os, requests

response = requests.post(
  "https://api.cloudmetis.com/v1/sms/send",
  headers={"Authorization": f"Bearer {os.environ['CLOUDMETIS_API_KEY']}"},
  json={"to": "0712345678", "message": "Your order #1042 has shipped."},
  timeout=30,
)
print(response.json()["message_id"])

Node.js

const response = await fetch('https://api.cloudmetis.com/v1/sms/send', {
method: 'POST',
headers: {
  Authorization: `Bearer ${process.env.CLOUDMETIS_API_KEY}`,
  'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '0712345678', message: 'Your order #1042 has shipped.' }),
});
const data = await response.json();
console.log(data.message_id);

Response (201 Created):

{
  "status": "accepted",
  "message_id": "msg_183",
  "to": "+254712345678",
  "message_status": "delivered",
  "recipients": 1,
  "sms_parts": 1,
  "batch_id": "bat_103",
  "units_used": 1,
  "units_available": 1000,
  "sandbox": true
}

In the sandbox every message is marked delivered immediately. With a live key you would normally see sent first, then a webhook when the network confirms delivery.

4. Check the message status

curl https://api.cloudmetis.com/v1/sms/status/msg_183 \
  -H "Authorization: Bearer cm_test_your_key"

5. Receive a delivery report

1. Open webhook.site and copy your unique URL.
2. In Developer API, click the pencil next to your key's webhook, paste the URL and save.
3. Send another message. A signed sms.status event arrives at webhook.site within seconds.

Then read Webhooks to verify the signature on your own server.

Go live

1. Make sure your organisation has an approved sender ID and SMS units (both in the app).
2. Create a Live key and swap it in for the test key. Nothing else changes.
3. Live webhook URLs must use https.