Reminders

Recurring scheduled SMS on autopilot — daily, weekly, monthly, annually or end-of-month, to a contact group or a pre-written per-recipient list. Set it once; the platform fires it at the right time in Africa/Nairobi.

Endpoints live under /api/v1/ with a scoped mbs_ token or JWT. Each firing is dispatched as a normal send and billed in units from your SMS balance— if the balance can't cover a firing, that occurrence fails and the reminder tries again on its next scheduled day.

Create a reminder

POST/api/v1/reminders

Parameters

Field	Type	Required	Description
name	string	Yes	Internal label.
frequency	string	Yes	`daily`, `weekly`, `monthly`, `annually`, `end_of_month`.
frequency_value	string	No	Pairs with the frequency: weekly → ISO weekday `"1"`–`"7"` (Mon–Sun); monthly → day `"1"`–`"31"`; annually → `"MM-DD"`. Omit for daily / end_of_month.
time_to_send	"HH:MM"	Yes	Time of day, 24-hour, Africa/Nairobi.
audience	string	Yes	`group` — send message to every contact in a group; `list` — send each recipient their own pre-written message (added below).
group_uuid	uuid	No	Required for group audience — the contact group to send to.
message	string	Yes	The body. For group audience, `{{name}}` is filled per contact when personalized is true.
personalized	boolean	No	Group audience only: render {{name}} from each contact.
name_format	string	No	`first` (default) or `full` — which contact name fills `{{name}}`.
sender_uuid	uuid	No	An approved sender ID. Omit to use the team default.
enabled	boolean	No	Defaults to true. Disabled reminders keep their schedule but skip firings.

curl -X POST https://api.mobilesasa.com/api/v1/reminders \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Friday market prices",
    "frequency": "weekly",
    "frequency_value": "5",
    "time_to_send": "08:30",
    "audience": "group",
    "group_uuid": "7d1a44f0-…",
    "message": "Habari {{name}}! Today's market prices are out — dial *384*45# for the full list.",
    "personalized": true
  }'

List-audience recipients

POST/api/v1/reminders/{uuid}/recipients

GET/api/v1/reminders/{uuid}/recipients

For audience: list, each recipient carries their own message — perfect for payment reminders where every customer owes a different amount. Post batches (up to ~1,000 per request):

curl -X POST https://api.mobilesasa.com/api/v1/reminders/2fd08e11-…/recipients \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "msisdn": "0712345678",
        "message": "Hi Jane, your loan instalment of KES 2,400 is due tomorrow."
      },
      {
        "msisdn": "0723456789",
        "message": "Hi Otieno, your loan instalment of KES 5,100 is due tomorrow."
      }
    ]
  }'

Response — 200

{
  "success": true,
  "data": { "inserted": 2, "invalid": 0 }
}

Individual rows can be corrected or removed with PUT/DELETE /reminders/{uuid}/recipients/{ruuid}.

Manage & monitor

GET/api/v1/reminders

GET/api/v1/reminders/{uuid}

PUT/api/v1/reminders/{uuid}

POST/api/v1/reminders/{uuid}/toggle

DELETE/api/v1/reminders/{uuid}

The list filters by q, frequency, enabled, sender and a from/to last-sent window. Each reminder reports last_sent_at and the UUID of the campaign its last firing created — every firing is a campaign with source_type: reminder, so progress and per-recipient delivery live on the campaign endpoints you already know.

curl "https://api.mobilesasa.com/api/v1/reminders?frequency=weekly&enabled=true&page=1" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Firing semantics worth knowing

A reminder fires at most once per day — when its time passes, the occurrence is claimed atomically, so restarts and multiple platform replicas never double-send. Weekdays are ISO (1 = Monday … 7 = Sunday). Monthly day 31 simply doesn't fire in shorter months — use end_of_month for "last day" semantics.

Anniversaries are their own thing

Birthday and anniversary messages keyed to each contact's own date live on the Anniversaries API — same product, different scheduling model.