MoSMS Developer API

Register (Create Account)

Self-service sign-up. Creates a new tenant organization plus its first admin user, and returns a Bearer token you can use immediately — no separate login call needed.

The org_name is slugified to derive a unique organization slug; if the slug or email is already taken you get a 422.

Headers

Request body

{
  "org_name": "Acme Traders",
  "phone": "255712345678",
  "name": "Jane Doe",
  "email": "jane@acme.co.tz",
  "password": "SecurePass123",
  "password_confirmation": "SecurePass123"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/register' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "org_name": "Acme Traders",
  "phone": "255712345678",
  "name": "Jane Doe",
  "email": "jane@acme.co.tz",
  "password": "SecurePass123",
  "password_confirmation": "SecurePass123"
}'

Example responses

{
  "message": "Registration successful.",
  "token": "1|abcdEFGH1234567890tokenExample",
  "user_type": "user",
  "user": {
    "id": 12,
    "name": "Jane Doe",
    "email": "jane@acme.co.tz",
    "role": "admin",
    "tenant": {
      "id": 7,
      "name": "Acme Traders",
      "slug": "acme-traders"
    }
  }
}

{
  "message": "An organization with this name already exists."
}

Login

Unified login for both tenant (developer) accounts and platform Super Admins — it checks the admin table first, then falls back to tenant users. Returns a Sanctum Bearer token to use on every subsequent request as Authorization: Bearer <token>, plus the caller's permissions list (granular RBAC — check this before assuming an endpoint is reachable).

Headers

Request body

{
  "email": "jane@acme.co.tz",
  "password": "SecurePass123"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/login' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "email": "jane@acme.co.tz",
  "password": "SecurePass123"
}'

Example responses

{
  "token": "1|abcdEFGH1234567890tokenExample",
  "user_type": "user",
  "user": {
    "id": 12,
    "name": "Jane Doe",
    "email": "jane@acme.co.tz",
    "role": "admin",
    "tenant": {
      "id": 7,
      "name": "Acme Traders",
      "slug": "acme-traders"
    }
  },
  "permissions": [
    "dashboard",
    "messages",
    "messages.send",
    "bulk_sms.send",
    "group_sms.send",
    "contacts",
    "groups",
    "templates"
  ]
}

{
  "message": "Invalid credentials."
}

{
  "message": "Your organization is inactive. Contact support."
}

Forgot Password

Requests a password-reset email. Always returns 200 regardless of whether the email exists, to avoid leaking which emails are registered.

Headers

Request body

{
  "email": "jane@acme.co.tz"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/forgot-password' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "email": "jane@acme.co.tz"
}'

Example responses

{
  "message": "If that email exists, a reset link has been sent."
}

Reset Password

Completes a password reset using the token emailed by Forgot Password. Tokens expire after 60 minutes.

Headers

Request body

{
  "token": "the-token-from-the-email",
  "email": "jane@acme.co.tz",
  "password": "NewSecurePass456",
  "password_confirmation": "NewSecurePass456"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/reset-password' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "token": "the-token-from-the-email",
  "email": "jane@acme.co.tz",
  "password": "NewSecurePass456",
  "password_confirmation": "NewSecurePass456"
}'

Example responses

{
  "message": "Your password has been reset. You can now log in."
}

{
  "message": "This reset link is invalid or has already been used."
}

Get Current User

Returns the authenticated user's profile, tenant, and permission list. Useful right after login to confirm the token works and to know what the caller is allowed to do.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/me' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Get Profile

Returns the authenticated user's profile (id, name, email, role, tenant).

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/profile' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Update Profile

Updates the caller's name/email, and optionally changes password (requires current_password).

Headers

Request body

{
  "name": "Jane Doe",
  "email": "jane@acme.co.tz",
  "current_password": "SecurePass123",
  "new_password": "EvenMoreSecure789",
  "new_password_confirmation": "EvenMoreSecure789"
}

Example request (curl)

curl --location --request PATCH 'https://mosms.co.tz/api/profile' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Jane Doe",
  "email": "jane@acme.co.tz",
  "current_password": "SecurePass123",
  "new_password": "EvenMoreSecure789",
  "new_password_confirmation": "EvenMoreSecure789"
}'

Logout

Revokes the Bearer token used on this request. Call this when a client (script, app) is done using its token.

Headers

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/logout' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Get SMS Balance

Returns the tenant's remaining SMS credit balance. Check this before sending to avoid a 422 insufficient-balance error — 1 credit = 1 SMS segment (see Send Single SMS for segment math).

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/balance' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "sms_balance": 1520
}

Get Dashboard Summary

Aggregate counters for the tenant: users, contacts, groups, messages (total + today), plus upcoming holiday/birthday auto-wish previews.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/dashboard' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "users_count": 3,
  "contacts_count": 240,
  "groups_count": 5,
  "messages_count": 18432,
  "messages_today": 56,
  "upcoming_holiday": null,
  "upcoming_birthdays": [
    {
      "id": 4,
      "name": "Amina Suleiman",
      "phone": "255712345678",
      "birth_date": "1990-07-20",
      "days_until": 3,
      "upcoming_age": 36
    }
  ],
  "birthday_wishes_enabled": true
}

Send Single SMS

Sends one SMS immediately (or schedules it for later with scheduled_at). Requires the messages.send permission.

Body parameters

Credit cost: GSM-7 messages cost 1 credit per 160 characters; messages containing Unicode (emoji, non-Latin scripts) cost 1 credit per 70 characters. The gateway rejects the request with 422 if your balance can't cover the segment count.

Headers

Request body

{
  "to": "0712345678",
  "text": "Hello from MoSMS!",
  "scheduled_at": null
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/sms/send' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "to": "0712345678",
  "text": "Hello from MoSMS!",
  "scheduled_at": null
}'

Example responses

{
  "data": {
    "id": 1042,
    "to_number": "255712345678",
    "from_sender": "MOSMS",
    "body": "Hello from MoSMS!",
    "status": "PENDING_ACCEPTED",
    "delivery_status": null,
    "delivered_at": null,
    "delivery_error": null,
    "gateway_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "gateway_response": {
      "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "sent_at": "2026-07-17T10:00:00.000000Z",
    "scheduled_at": null,
    "contact": null,
    "group": null,
    "user": null,
    "created_at": "2026-07-17T10:00:00.000000Z"
  }
}

{
  "message": "Insufficient SMS balance. Message requires 2 credit(s) but you have 0 remaining.",
  "balance": 0,
  "required": 2
}

Send Bulk SMS

Queues up to any number of distinct messages for background delivery (does not send synchronously — you'll get a 202 immediately, then track each message via List Messages). Requires bulk_sms.send.

Body parameters

Headers

Request body

{
  "messages": [
    {
      "to": "0712345678",
      "text": "Hi Juma, your order has shipped!"
    },
    {
      "to": "0765432109",
      "text": "Hi Amina, your order has shipped!"
    }
  ]
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/sms/send-bulk' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "messages": [
    {
      "to": "0712345678",
      "text": "Hi Juma, your order has shipped!"
    },
    {
      "to": "0765432109",
      "text": "Hi Amina, your order has shipped!"
    }
  ]
}'

Example responses

{
  "message": "Bulk SMS queued for delivery.",
  "count": 2
}

{
  "message": "Insufficient SMS balance. Messages require 2 credit(s) but you have 0 remaining.",
  "balance": 0,
  "required": 2
}

Send SMS to Group

Sends (queues) the same message to every contact in a saved Group. Requires group_sms.send.

Path parameter: group_id — the group's numeric ID (see Groups folder).

Body: same text / template_id / scheduled_at fields as Send Single SMS. Returns 422 if the group has no contacts or the balance can't cover contacts_count × segments_per_message.

Headers

Request body

{
  "text": "Reminder: our office is closed tomorrow for the public holiday.",
  "template_id": null,
  "scheduled_at": null
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/sms/send-group/:group_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "text": "Reminder: our office is closed tomorrow for the public holiday.",
  "template_id": null,
  "scheduled_at": null
}'

Example responses

{
  "message": "Group SMS to 'VIP Customers' queued for delivery.",
  "contacts": 84
}

{
  "message": "Group has no contacts."
}

List Messages

Paginated history of every message sent (or queued/scheduled) by the tenant, newest first.

Query parameters (all optional): status (e.g. PENDING_ACCEPTED, DELIVERED, scheduled, cancelled), search (matches to_number or body), date_from, date_to (both YYYY-MM-DD, filtered on sent_at), page.

Headers

Query parameters

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/messages' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": [
    {
      "id": 1042,
      "to_number": "255712345678",
      "from_sender": "MOSMS",
      "body": "Hello from MoSMS!",
      "status": "DELIVERED",
      "delivery_status": "DELIVERED_TO_HANDSET",
      "delivered_at": "2026-07-17T10:00:05.000000Z",
      "delivery_error": null,
      "gateway_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sent_at": "2026-07-17T10:00:00.000000Z",
      "scheduled_at": null,
      "created_at": "2026-07-17T10:00:00.000000Z"
    }
  ],
  "links": {
    "first": "https://mosms.co.tz/api/messages?page=1",
    "last": "https://mosms.co.tz/api/messages?page=12",
    "prev": null,
    "next": "https://mosms.co.tz/api/messages?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 12,
    "per_page": 20,
    "total": 231
  }
}

Get Message

Fetches a single message by ID, with its linked contact/group/user (when present).

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/messages/:message_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Check Delivery Status

Actively polls the upstream SMS gateway for the latest delivery report on this message and updates status / delivery_status / delivered_at / delivery_error accordingly, then returns the refreshed message. Requires messages.check_status.

Errors: 422 if the message has no gateway_message_id (e.g. it's still scheduled), 404 if the gateway has no report yet, 429 if the gateway rate-limited us, 502 if the gateway is unreachable.

Headers

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/messages/:message_id/check-status' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": {
    "id": 1042,
    "to_number": "255712345678",
    "status": "DELIVERED",
    "delivery_status": "DELIVERED_TO_HANDSET",
    "delivered_at": "2026-07-17T10:00:05.000000Z",
    "delivery_error": null
  }
}

{
  "message": "This message has no gateway ID \u2014 status cannot be checked."
}

Cancel Scheduled Message

Cancels a message that hasn't been sent yet (status === 'scheduled'). Requires messages.cancel_scheduled. Returns 422 if the message already sent.

Headers

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/messages/:message_id/cancel' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "message": "Only scheduled messages can be cancelled."
}

Bulk Delete Messages

Permanently deletes multiple message records by ID. Requires messages.delete.

Headers

Request body

{
  "ids": [
    1042,
    1043,
    1044
  ]
}

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/messages/bulk' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "ids": [
    1042,
    1043,
    1044
  ]
}'

Example responses

{
  "message": "Messages deleted.",
  "count": 3
}

List Delivery Reports

Proxies straight through to the upstream carrier's native delivery-report endpoint and returns its raw JSON — useful for reconciling against gateway-side records directly. Requires delivery_reports.

Query: messageId (optional, filters to one message), limit (default 25).

Headers

Query parameters

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/delivery-reports' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "message": "Unable to reach the SMS gateway. Please try again later."
}

List SMS Logs

Tenant-scoped raw send logs proxied from the upstream gateway (distinct from List Messages, which is MoSMS's own local record). Requires sms_logs.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/sms-logs' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List Contacts

Paginated contact list. Query: search (matches name/phone), page.

Headers

Query parameters

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/contacts' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": [
    {
      "id": 501,
      "name": "Juma Hassan",
      "phone": "255712345678",
      "email": null,
      "birth_date": null,
      "groups": [],
      "created_at": "2026-01-10T08:00:00.000000Z",
      "updated_at": "2026-01-10T08:00:00.000000Z"
    }
  ],
  "links": {},
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 58
  }
}

Create Contact

name and phone are required; phone must be unique per tenant (normalized before the uniqueness check). birth_date (if set) powers the birthday auto-SMS feature.

Headers

Request body

{
  "name": "Juma Hassan",
  "phone": "0712345678",
  "email": "juma@example.com",
  "birth_date": "1988-03-14"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/contacts' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Juma Hassan",
  "phone": "0712345678",
  "email": "juma@example.com",
  "birth_date": "1988-03-14"
}'

Example responses

{
  "data": {
    "id": 501,
    "name": "Juma Hassan",
    "phone": "255712345678",
    "email": "juma@example.com",
    "birth_date": "1988-03-14",
    "groups": []
  }
}

Get Contact

Fetch one contact with its groups loaded.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/contacts/:contact_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Update Contact

All fields optional (sometimes validation) — send only what changes.

Headers

Request body

{
  "name": "Juma Hassan Mnyonge",
  "phone": "0712345678",
  "email": "juma@example.com"
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/contacts/:contact_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Juma Hassan Mnyonge",
  "phone": "0712345678",
  "email": "juma@example.com"
}'

Delete Contact

Permanently deletes one contact.

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/contacts/:contact_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Bulk Delete Contacts

Deletes multiple contacts by ID.

Headers

Request body

{
  "ids": [
    501,
    502,
    503
  ]
}

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/contacts/bulk' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "ids": [
    501,
    502,
    503
  ]
}'

Example responses

{
  "message": "Contacts deleted.",
  "count": 3
}

Import Contacts (CSV)

Multipart upload. CSV columns: name, phone, email, birth_date (header row required). Max 5MB.

Headers

Form data (multipart)

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/contacts/import/csv' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json' \
  --form 'file=@/path/to/your/file'

Import Contacts (vCard)

Multipart upload of a .vcf vCard export (e.g. exported from a phone's contacts app). Max 5MB.

Headers

Form data (multipart)

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/contacts/import/vcf' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json' \
  --form 'file=@/path/to/your/file'

List Groups

Paginated list of contact groups, with contacts_count on each.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/groups' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": [
    {
      "id": 9,
      "name": "VIP Customers",
      "description": "Top-tier clients",
      "contacts_count": 84,
      "created_at": "2026-02-01T00:00:00.000000Z",
      "updated_at": "2026-02-01T00:00:00.000000Z"
    }
  ]
}

Create Group

Creates an empty group — add contacts afterwards via Add Contacts to Group.

Headers

Request body

{
  "name": "VIP Customers",
  "description": "Top-tier clients"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/groups' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "VIP Customers",
  "description": "Top-tier clients"
}'

Example responses

{
  "data": {
    "id": 9,
    "name": "VIP Customers",
    "description": "Top-tier clients",
    "contacts_count": 0
  }
}

Get Group

Fetch one group with its contacts_count.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/groups/:group_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Update Group

Rename a group or change its description.

Headers

Request body

{
  "name": "VIP Customers (Tier 1)",
  "description": "Top-tier clients"
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/groups/:group_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "VIP Customers (Tier 1)",
  "description": "Top-tier clients"
}'

Delete Group

Deletes the group (contacts themselves are not deleted, only the grouping).

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/groups/:group_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List Group Contacts

Paginated list of contacts that belong to this group.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/groups/:group_id/contacts' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Add Contacts to Group

Attaches existing contacts (by ID) to the group — safe to call repeatedly, duplicates are ignored.

Headers

Request body

{
  "contact_ids": [
    501,
    502,
    503
  ]
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/groups/:group_id/contacts' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "contact_ids": [
    501,
    502,
    503
  ]
}'

Example responses

{
  "message": "Contacts added to group."
}

Remove Contacts from Group

Detaches contacts from the group without deleting the contacts themselves.

Headers

Request body

{
  "contact_ids": [
    501
  ]
}

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/groups/:group_id/contacts' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "contact_ids": [
    501
  ]
}'

Example responses

{
  "message": "Contacts removed from group."
}

List Templates

Paginated list of saved message templates.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/templates' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Create Template

body supports {name}, {phone}, and {email} placeholders, filled in per-contact when the template is used in a send.

Headers

Request body

{
  "name": "Order Shipped",
  "body": "Hi {name}, your order has shipped! Track it at example.com/track."
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/templates' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Order Shipped",
  "body": "Hi {name}, your order has shipped! Track it at example.com/track."
}'

Example responses

{
  "data": {
    "id": 3,
    "name": "Order Shipped",
    "body": "Hi {name}, your order has shipped! Track it at example.com/track.",
    "created_at": "2026-01-05T00:00:00.000000Z"
  }
}

Get Template

Fetch one template.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/templates/:template_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Update Template

Updates a template's name and/or body.

Headers

Request body

{
  "name": "Order Shipped",
  "body": "Hi {name}, your order #{phone} has shipped!"
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/templates/:template_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Order Shipped",
  "body": "Hi {name}, your order #{phone} has shipped!"
}'

Delete Template

Deletes a template.

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/templates/:template_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List SMS Packages

Public price tiers available for purchase (no purchase_sms permission required to view).

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/sms-packages' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": [
    {
      "id": 1,
      "name": "Starter",
      "min_quantity": 100,
      "max_quantity": 999,
      "price_per_sms": 20
    },
    {
      "id": 2,
      "name": "Growth",
      "min_quantity": 1000,
      "max_quantity": 9999,
      "price_per_sms": 18
    }
  ]
}

Purchase SMS Credits (Manual)

Submits a manual top-up request (e.g. after a bank/mobile-money transfer) for admin approval — credits are not added instantly. sms_quantity must be ≥100 for SMS or ≥10 for channel: whatsapp. Only one pending manual request per channel is allowed at a time.

Headers

Request body

{
  "sms_quantity": 1000,
  "transaction_reference": "MPESA-XJ29KD8",
  "payer_phone": "0712345678"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/sms-purchases' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "sms_quantity": 1000,
  "transaction_reference": "MPESA-XJ29KD8",
  "payer_phone": "0712345678"
}'

Example responses

{
  "message": "Purchase request submitted successfully.",
  "data": {
    "id": 88,
    "sms_quantity": 1000,
    "total_amount": 20000,
    "status": "pending"
  }
}

{
  "message": "You already have a pending SMS purchase of 500 credits (Ref: MPESA-AB12CD) awaiting approval. Please wait for it to be approved before creating a new one.",
  "pending_id": 87
}

Purchase via Pesapal

Initiates an online card/mobile-money checkout through Pesapal. Returns a redirect_url — send the user there to complete payment, then poll Check Pesapal Purchase Status.

Headers

Request body

{
  "sms_quantity": 1000
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/sms-purchases/pesapal' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "sms_quantity": 1000
}'

Example responses

{
  "message": "Pesapal checkout initiated.",
  "data": {
    "payment_id": 89,
    "redirect_url": "https://pay.pesapal.com/...",
    "order_tracking_id": "..."
  }
}

Check Pesapal Purchase Status

Polls Pesapal for the latest status of a pending online payment and updates the local record.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/sms-purchases/:purchase_id/status' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": {
    "id": 89,
    "status": "approved",
    "payment_status_description": "COMPLETED",
    "confirmation_code": "ABC123",
    "payment_method": "pesapal",
    "sms_quantity": 1000,
    "total_amount": 18000
  }
}

List Purchase History

Paginated history of the tenant's SMS/WhatsApp credit purchases.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/sms-purchases' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Download Purchase Receipt

Streams a PDF receipt for an approved purchase. Only available once status === 'approved'.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/sms-purchases/:purchase_id/receipt' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List Events

Paginated list of events (weddings, harambees/fundraisers, etc.) with computed SMS-cost stats. Requires events. Query: search (matches name), status (draft/active/completed/cancelled), page.

Headers

Query parameters

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/events' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "data": [
    {
      "id": 12,
      "name": "Amina & Juma's Wedding",
      "type": "wedding",
      "description": null,
      "event_date": "2026-09-12",
      "venue": "Kigamboni Beach Hall",
      "target_amount": 5000000,
      "status": "active",
      "invitees_count": 84,
      "payments_count": 12,
      "sms_stages_count": 3,
      "total_pledged": 3200000,
      "total_collected": 1450000,
      "total_sms": 252,
      "sent_sms": 84,
      "sms_cost": 5040,
      "created_at": "2026-06-01T09:00:00.000000Z"
    }
  ]
}

Create Event

Body parameters

Requires events.add.

Headers

Request body

{
  "name": "Amina & Juma's Wedding",
  "type": "wedding",
  "event_date": "2026-09-12",
  "venue": "Kigamboni Beach Hall",
  "target_amount": 5000000
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Amina & Juma'\''s Wedding",
  "type": "wedding",
  "event_date": "2026-09-12",
  "venue": "Kigamboni Beach Hall",
  "target_amount": 5000000
}'

Example responses

{
  "data": {
    "id": 12,
    "name": "Amina & Juma's Wedding",
    "type": "wedding",
    "event_date": "2026-09-12",
    "status": "draft",
    "invitees_count": 0
  }
}

Get Event

Fetch one event, including total_pledged/total_collected totals. Requires events.view.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/events/:event_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Update Event

Same fields as Create Event, all optional (sometimes validation). Requires events.edit.

Headers

Request body

{
  "status": "active"
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/events/:event_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "status": "active"
}'

Delete Event

Requires events.delete. This also removes the event's invitees, payments, and SMS stages.

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/events/:event_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List Event Invitees

Paginated. Query: search (matches name/phone), page. Requires events.view.

Headers

Query parameters

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/events/:event_id/invitees' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Add Invitee

name and phone required; pledge_amount and contact_id (link to an existing Contact) optional. Requires events.manage_invitees.

Headers

Request body

{
  "name": "Fatuma Rajabu",
  "phone": "0712345678",
  "pledge_amount": 50000
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events/:event_id/invitees' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "Fatuma Rajabu",
  "phone": "0712345678",
  "pledge_amount": 50000
}'

Example responses

{
  "data": {
    "id": 501,
    "event_id": 12,
    "name": "Fatuma Rajabu",
    "phone": "255712345678",
    "pledge_amount": 50000,
    "paid_amount": 0,
    "status": "pending"
  }
}

Import Invitees (from Contacts/Group)

Bulk-adds invitees from existing Contacts and/or a Group — pass contact_ids (array) and/or group_id (at least one required). Duplicates (already-invited contacts) are skipped. Requires events.manage_invitees.

Headers

Request body

{
  "group_id": 9,
  "contact_ids": [
    501,
    502
  ]
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events/:event_id/invitees/import' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "group_id": 9,
  "contact_ids": [
    501,
    502
  ]
}'

Example responses

{
  "message": "42 invitees imported.",
  "imported": 42
}

Import Invitees (CSV/vCard file)

Multipart upload — CSV (with name/phone/email columns) or .vcf vCard export. Max 5MB. Requires events.manage_invitees.

Headers

Form data (multipart)

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events/:event_id/invitees/import/file' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json' \
  --form 'file=@/path/to/your/file'

Example responses

{
  "message": "38 invitees imported, 4 skipped.",
  "imported": 38,
  "skipped": 4
}

Update Invitee

All fields optional. status is one of pending, invited, confirmed, declined. Requires events.manage_invitees.

Headers

Request body

{
  "status": "confirmed",
  "pledge_amount": 60000
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/events/:event_id/invitees/:invitee_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "status": "confirmed",
  "pledge_amount": 60000
}'

Remove Invitee

Requires events.manage_invitees.

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/events/:event_id/invitees/:invitee_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List Event Payments

Paginated, newest first, with invitee + recorder loaded. Requires events.view.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/events/:event_id/payments' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Record a Payment

Records a pledge payment against an invitee. If the event has auto_payment_sms enabled, a thank-you SMS is sent automatically. Requires events.manage_payments.

Body parameters

Headers

Request body

{
  "event_invitee_id": 501,
  "amount": 50000,
  "payment_method": "mobile_money",
  "reference": "MPESA-XJ29KD8",
  "payment_date": "2026-07-18"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events/:event_id/payments' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "event_invitee_id": 501,
  "amount": 50000,
  "payment_method": "mobile_money",
  "reference": "MPESA-XJ29KD8",
  "payment_date": "2026-07-18"
}'

Example responses

{
  "data": {
    "id": 88,
    "event_id": 12,
    "event_invitee_id": 501,
    "amount": 50000,
    "payment_method": "mobile_money",
    "reference": "MPESA-XJ29KD8",
    "payment_date": "2026-07-18"
  }
}

Update Payment

All fields optional. Requires events.manage_payments.

Headers

Request body

{
  "amount": 55000
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/events/:event_id/payments/:payment_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "amount": 55000
}'

Delete Payment

Requires events.manage_payments.

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/events/:event_id/payments/:payment_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

List SMS Stages

Each stage includes computed stage_total_sms/stage_remaining/stage_cost based on the current invitee count. Requires events.view.

Headers

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/events/:event_id/sms-stages' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Create SMS Stage

Defines a message (SMS or WhatsApp) to send to all invitees, once or on a recurring schedule. SMS and WhatsApp are always separate stages — there's no combined "both" channel; create one stage per channel if you want to reach invitees on both. Requires events.send_sms.

Body parameters

Creating a stage does not send it — call Send SMS Stage (or let it fire on send_at).

Headers

Request body

{
  "stage_type": "invitation",
  "name": "Save the Date",
  "channel": "sms",
  "body": "You're invited to {invitee_name}'s wedding on {event_date} at {venue}!",
  "send_at": "2026-08-01T09:00:00",
  "frequency": "once"
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events/:event_id/sms-stages' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "stage_type": "invitation",
  "name": "Save the Date",
  "channel": "sms",
  "body": "You'\''re invited to {invitee_name}'\''s wedding on {event_date} at {venue}!",
  "send_at": "2026-08-01T09:00:00",
  "frequency": "once"
}'

Example responses

{
  "data": {
    "id": 7,
    "event_id": 12,
    "stage_type": "invitation",
    "name": "Save the Date",
    "status": "draft",
    "sent_count": 0
  }
}

Update SMS Stage

Same fields as Create SMS Stage. status may additionally be set to cancelled. Requires events.send_sms.

Headers

Request body

{
  "status": "scheduled"
}

Example request (curl)

curl --location --request PUT 'https://mosms.co.tz/api/events/:event_id/sms-stages/:stage_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "status": "scheduled"
}'

Delete SMS Stage

Requires events.send_sms.

Headers

Example request (curl)

curl --location --request DELETE 'https://mosms.co.tz/api/events/:event_id/sms-stages/:stage_id' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Send SMS Stage

Queues the stage's message to every eligible invitee now. WhatsApp stages are metered against the tenant's WhatsApp wallet (not the SMS balance) and billed per conversation. SMS stages are checked against the SMS credit balance the same way as Send SMS to Group. Requires events.send_sms.

Headers

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/events/:event_id/sms-stages/:stage_id/send' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Accept: application/json'

Example responses

{
  "message": "Sending 84 message(s). You'll be notified when complete."
}

{
  "message": "This stage has already been sent."
}

{
  "message": "No invitees are eligible for this stage."
}

Delivery Callback (carrier → MoSMS)

Not called by developers. This is the endpoint the upstream SMS carrier calls to push delivery-status updates for messages MoSMS sent on your behalf. Documented here only so you understand where delivery_status on a message comes from — you don't need to (and can't meaningfully) call this yourself.

There is currently no outbound webhook that notifies *your* systems when a message's status changes — poll Check Delivery Status or List Messages instead.

Headers

Request body

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "DELIVERED_TO_HANDSET",
  "error": null
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/webhooks/delivery' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "DELIVERED_TO_HANDSET",
  "error": null
}'

Example responses

{
  "message": "OK"
}

WhatsApp Webhook — Verify (Meta → MoSMS)

Not called by developers. Meta's webhook-verification handshake for the tenant's WhatsApp Cloud API integration.

Headers

Query parameters

Example request (curl)

curl --location --request GET 'https://mosms.co.tz/api/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...' \
  --header 'Accept: application/json'

WhatsApp Webhook — Receive (Meta → MoSMS)

Not called by developers. Meta pushes WhatsApp delivery statuses (sent/delivered/read/failed) and inbound message replies here. Verified via X-Hub-Signature-256 HMAC when WHATSAPP_APP_SECRET is configured.

Headers

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/webhooks/whatsapp' \
  --header 'Accept: application/json'

[Planned] Send Single WhatsApp Message

⚠️ Not yet available on the public API. WhatsApp sending today only exists in the internal MoSMS dashboard (session-authenticated web routes), metered against the tenant's whatsapp_balance wallet — mirroring Send Single SMS, but via App\Services\WhatsApp\WhatsAppCloudService instead of the SMS gateway.

This item documents the shape a future token-authenticated /api/whatsapp/send endpoint would likely take, based on the existing dashboard implementation, so client integrations can be planned ahead of time. Confirm with the MoSMS team before building against it.

Headers

Request body

{
  "to": "0712345678",
  "whatsapp_template_id": 4,
  "text": null
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/whatsapp/send' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "to": "0712345678",
  "whatsapp_template_id": 4,
  "text": null
}'

[Planned] Send Bulk WhatsApp Broadcast

⚠️ Not yet available on the public API. Modeled on the internal bulk/group broadcast flow (channel: whatsapp), which requires an approved, no-variable WhatsApp template and is metered 1 WhatsApp credit per recipient. Confirm with the MoSMS team before building against it.

Headers

Request body

{
  "numbers": [
    "0712345678",
    "0765432109"
  ],
  "whatsapp_template_id": 4
}

Example request (curl)

curl --location --request POST 'https://mosms.co.tz/api/whatsapp/send-bulk' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "numbers": [
    "0712345678",
    "0765432109"
  ],
  "whatsapp_template_id": 4
}'