{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/masokodigital.co.tz" } ], "info": { "name": "MasokoDigital API Reference", "_postman_id": "f7b2d5d4-7f93-4cc7-8d18-0090d5a1dbbf", "description": "Send SMS, track delivery and pull reporting straight from your own systems.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "SMS", "description": "\nSend messages, check your balance, and pull delivery reporting.", "item": [ { "name": "Send a single SMS", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/send\/single", "query": [], "raw": "{{baseUrl}}\/api\/sms\/send\/single" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"sender_id\":\"MASOKO\",\"message\":\"Hello from MasokoDigital\",\"recipient\":\"255700000000\"}" }, "description": "Sends one message to one recipient. The sender ID must already be\napproved - call `GET \/api\/sms\/senders` to see which of yours are." }, "response": [ { "header": [], "code": 200, "body": "{\"message\":\"2026-08-12 09:00:00 API campaign SMS Campaign Processing...\",\"status\":\"Processing\",\"campaign_id\":\"9b1f...c3\"}", "name": "" }, { "header": [], "code": 400, "body": "{\"error\":{\"recipient\":[\"The recipient field is required.\"]}}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":\"Sender ID Not Found\"}", "name": "" } ] }, { "name": "Send bulk SMS", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/send\/bulk", "query": [], "raw": "{{baseUrl}}\/api\/sms\/send\/bulk" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"sender_id\":\"MASOKO\",\"message\":\"Hello from MasokoDigital\",\"recipients\":[\"255700000000\",\"255711111111\"]}" }, "description": "Sends the same message to many recipients in one call. Recipients are\nprocessed in chunks; the response returns as soon as the campaign is\naccepted, so poll the campaign statistics endpoint for delivery." }, "response": [ { "header": [], "code": 200, "body": "{\"message\":\"2026-08-12 09:00:00 API campaign SMS Campaign Processing...\",\"status\":\"Processing\",\"campaign_id\":\"9b1f...c3\"}", "name": "" }, { "header": [], "code": 400, "body": "{\"error\":\"Campaign has no contacts\"}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":\"Sender ID Not Found\"}", "name": "" } ] }, { "name": "Get SMS balance", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/balance", "query": [], "raw": "{{baseUrl}}\/api\/sms\/balance" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Remaining SMS credits on your account." }, "response": [ { "header": [], "code": 200, "body": "{\"balance\":4612}", "name": "" } ] }, { "name": "Message counts by status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/campaign\/sms\/report", "query": [ { "key": "start", "value": "2026-01-01", "description": "date Start of the range.", "disabled": false }, { "key": "end", "value": "2026-12-31", "description": "date End of the range.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/campaign\/sms\/report?start=2026-01-01&end=2026-12-31" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"start\":\"2026-09-06T16:14:20\",\"end\":\"2026-09-06T16:14:20\"}" }, "description": "Totals per delivery status over a date range.\n\nThe `message` field is a legacy string kept for existing integrations;\nprefer the `data` object, which carries the same counts keyed by status." }, "response": [ { "header": [], "code": 200, "body": "{\"message\":\"[\\\"DELIVRD\\\",\\\"Success\\\"] -> [155,614]\",\"data\":{\"DELIVRD\":155,\"Success\":614},\"total\":769,\"start\":\"2026-01-01T00:00:00.000000Z\",\"end\":null}", "name": "" } ] }, { "name": "List campaigns", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/campaigns", "query": [ { "key": "start", "value": "2026-01-01", "description": "date Only campaigns created on or after this date.", "disabled": false }, { "key": "end", "value": "2026-12-31", "description": "date Only campaigns created on or before this date.", "disabled": false }, { "key": "per_page", "value": "50", "description": "Results per page, 1-200. Defaults to 25.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/sms\/campaigns?start=2026-01-01&end=2026-12-31&per_page=50" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"start\":\"2026-09-06T16:14:20\",\"end\":\"2026-09-06T16:14:20\",\"per_page\":21}" }, "description": "Your campaigns, newest first. Useful for recovering a `campaign_id` you\ndid not keep from the send response." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"campaign_id\":\"9b1f...c3\",\"name\":\"2026-08-12 API campaign\",\"status\":\"Completed\",\"messages\":120,\"created_at\":\"2026-08-12T09:00:00.000000Z\"}],\"meta\":{\"current_page\":1,\"last_page\":4,\"per_page\":25,\"total\":98}}", "name": "" } ] }, { "name": "List sender IDs", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/senders", "query": [], "raw": "{{baseUrl}}\/api\/sms\/senders" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Your approved sender IDs. Only these can be used to send - anything else\nis rejected with `404 Sender ID Not Found`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"sender_id\":\"MASOKO\",\"is_default\":true}]}", "name": "" } ] }, { "name": "Get campaign statistics", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/campaign\/sms\/statistics\/:campaign_scuuid", "query": [], "raw": "{{baseUrl}}\/api\/campaign\/sms\/statistics\/:campaign_scuuid", "variable": [ { "id": "campaign_scuuid", "key": "campaign_scuuid", "value": "86939523-bab7-40cf-8a9a-f57919c02980", "description": "" }, { "id": "campaign", "key": "campaign", "value": "9b1f...c3", "description": "The campaign_id returned when sending." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Delivery totals for one campaign." }, "response": [] }, { "name": "Get a message delivery report", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/report\/:sms_smsuuid", "query": [], "raw": "{{baseUrl}}\/api\/sms\/report\/:sms_smsuuid", "variable": [ { "id": "sms_smsuuid", "key": "sms_smsuuid", "value": "bcf8534f-aa13-4a66-948e-d1e45c9b35bf", "description": "" }, { "id": "sms", "key": "sms", "value": "9c2a...f1", "description": "The message identifier." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Delivery detail for a single message." }, "response": [] }, { "name": "Get delivery status for one recipient", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/report\/:campaign_scuuid\/:phone", "query": [], "raw": "{{baseUrl}}\/api\/sms\/report\/:campaign_scuuid\/:phone", "variable": [ { "id": "campaign_scuuid", "key": "campaign_scuuid", "value": "86939523-bab7-40cf-8a9a-f57919c02980", "description": "" }, { "id": "phone", "key": "phone", "value": "255700000000", "description": "Recipient MSISDN." }, { "id": "campaign", "key": "campaign", "value": "9b1f...c3", "description": "The campaign_id returned when sending." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Delivery status of a single recipient within a campaign." }, "response": [] }, { "name": "Full delivery breakdown", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/sms\/campaign\/report\/dates", "query": [ { "key": "start", "value": "2026-01-01", "description": "date Start of the range.", "disabled": false }, { "key": "end", "value": "2026-12-31", "description": "date End of the range.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/sms\/campaign\/report\/dates?start=2026-01-01&end=2026-12-31" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"start\":\"2026-09-06T16:14:20\",\"end\":\"2026-09-06T16:14:20\"}" }, "description": "Message counts broken down by delivery status, gender, age band and\nrecipient location over a date range." }, "response": [] } ] }, { "name": "WhatsApp", "description": "\nSend WhatsApp messages, check your balance, and see which of your numbers\nand templates are cleared for use.\n\nWhatsApp is stricter than SMS in two ways worth knowing before you\nintegrate. You can only send from a number Meta has approved, and you can\nonly *open* a conversation with a template Meta has approved - free-form\ntext is accepted solely inside the 24-hour window that a customer's own\nmessage opens.", "item": [ { "name": "Send a WhatsApp message", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/whatsapp\/send", "query": [], "raw": "{{baseUrl}}\/api\/whatsapp\/send" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"recipient\":\"255700000000\",\"message\":\"Hello Amina, your order 4471 has shipped.\",\"template\":\"9c2f4e10-77a1-4a0e-9a1d-2f3f9d0f1b22\",\"sender\":\"255700000002\\n\\nThe `status` returned is WhatsApp's acknowledgement, not proof of\\nreceipt. Poll `GET \\\/api\\\/whatsapp\\\/message\\\/{message_id}` to find out\\nwhether it was delivered and read.\"}" }, "description": "Sends one message to one recipient and bills one credit.\n\nPass `template` to open a conversation; without it the message is\nfree-form and will only be delivered if the recipient has messaged you\nwithin the last 24 hours. Omit `sender` to use your default number." }, "response": [ { "header": [], "code": 200, "body": "{\"message_id\":\"9b1f8c22-0b5e-4b1a-9a3a-1d2e3f4a5b6c\",\"status\":\"queued\",\"to\":\"255700000000\",\"from\":\"255700000002\",\"balance\":411}", "name": "" }, { "header": [], "code": 400, "body": "{\"error\":{\"recipient\":[\"The recipient field is required.\"]}}", "name": "" }, { "header": [], "code": 402, "body": "{\"error\":\"You do not have enough WhatsApp credits. Please buy more.\"}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":\"Template Not Found\"}", "name": "" } ] }, { "name": "Get WhatsApp balance", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/whatsapp\/balance", "query": [], "raw": "{{baseUrl}}\/api\/whatsapp\/balance" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Remaining WhatsApp credits on your account. One credit is one message." }, "response": [ { "header": [], "code": 200, "body": "{\"balance\":411}", "name": "" } ] }, { "name": "List WhatsApp numbers", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/whatsapp\/senders", "query": [], "raw": "{{baseUrl}}\/api\/whatsapp\/senders" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "The numbers registered to your account and where each one stands.\nOnly a number with status `approved` can send." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"number\":\"255700000002\",\"display_name\":\"Masoko Digital\",\"status\":\"approved\",\"is_default\":true}]}", "name": "" } ] }, { "name": "List WhatsApp templates", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/whatsapp\/templates", "query": [], "raw": "{{baseUrl}}\/api\/whatsapp\/templates" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Your templates and where each one stands. Only a template with status\n`approved` can be used to open a conversation; the others are listed so\nyou can see what is still in review and why anything was turned down.\n\n`variables` lists the placeholders in the body, in the order Meta\nexpects their values." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"template_id\":\"9c2f4e10-77a1-4a0e-9a1d-2f3f9d0f1b22\",\"name\":\"Order Update\",\"type\":\"utility\",\"language\":\"en\",\"body\":\"Hello {{1}}, your order {{2}} has shipped.\",\"variables\":[\"1\",\"2\"],\"status\":\"approved\",\"rejection_reason\":null}]}", "name": "" } ] }, { "name": "Get a message's delivery status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/whatsapp\/message\/:message", "query": [], "raw": "{{baseUrl}}\/api\/whatsapp\/message\/:message", "variable": [ { "id": "message", "key": "message", "value": "9b1f8c22-0b5e-4b1a-9a3a-1d2e3f4a5b6c", "description": "The message_id returned when sending." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Where one message got to, and when.\n\n`status` moves forward through `queued`, `sent`, `delivered` and `read`,\nand never backwards - so a message that reads `delivered` has been\ndelivered even if a later callback says otherwise. `failed` and\n`undelivered` are terminal, and carry the reason in `error`.\n\n`read` depends on the recipient having read receipts switched on. When\nthey are off, a message that was read stops at `delivered`, so treat a\nmissing `read_at` as \"not known\" rather than \"not read\"." }, "response": [ { "header": [], "code": 200, "body": "{\"message_id\":\"9b1f8c22-0b5e-4b1a-9a3a-1d2e3f4a5b6c\",\"status\":\"read\",\"to\":\"255700000000\",\"from\":\"255700000002\",\"direction\":\"outbound\",\"sent_at\":\"2026-09-06T09:00:00.000000Z\",\"delivered_at\":\"2026-09-06T09:00:04.000000Z\",\"read_at\":\"2026-09-06T09:12:31.000000Z\",\"error\":null}", "name": "" }, { "header": [], "code": 404, "body": "{\"error\":\"Message Not Found\"}", "name": "" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }