Scheduling & Drip

Schedule single messages or bulk campaigns for a future time, or send at a controlled drip rate.

Schedule a single message

Pass schedule_mode: "scheduled" and scheduled_at to any single-send request. The message is created and balance reserved immediately; it will be dispatched automatically when the scheduled time arrives.

POST /api/messages/send

{
  "to": "+256712345678",
  "text": "Your appointment is tomorrow at 10am. Reply 1 to confirm.",
  "sender_id": "ClinicApp",
  "schedule_mode": "scheduled",
  "scheduled_at": "2026-06-01T07:00:00Z"
}

The response will have "status": "scheduled" and include the scheduled_at timestamp:

{
  "id": "msg-a1b2c3d4",
  "status": "scheduled",
  "route": "ESMS_UG",
  "scheduled_at": "2026-06-01T07:00:00+00:00",
  ...
}

Constraint	Value
Minimum lead time	5 minutes from now
Maximum lead time	7 days
Timezone	Always UTC - convert before sending

Scheduled single messages appear in the Logs portal with a scheduled status badge.

Scheduling beyond 7 days is coming soon.

Scheduled bulk delivery

Schedule a bulk send to go out at a specific time. Useful for time-sensitive campaigns, reminders, or when you want to send during business hours in a specific timezone.

POST /api/messages/send-bulk

{
  "contact_list_ids": [1],
  "text": "Your appointment is tomorrow at 10am. Reply 1 to confirm.",
  "sender_id": "ClinicApp",
  "schedule_mode": "scheduled",
  "scheduled_at": "2026-06-01T07:00:00Z"
}

Constraints

Constraint	Value
Minimum lead time	5 minutes from now
Maximum lead time	7 days
Timezone	Always UTC - convert before sending

If your target audience is in East Africa (UTC+3), 9:00 AM local time = 06:00:00Z. Plan accordingly.

Status

The batch response will show "status": "scheduled". Scheduled messages appear in the Logs section of the portal.

You cannot currently cancel a scheduled batch via API. To cancel, delete the scheduled record in the portal before it dispatches.

Drip delivery

Drip mode sends messages at a controlled rate - useful when you want to manage delivery pace, avoid carrier throttling, or stagger notifications.

{
  "contact_list_ids": [3],
  "text": "Hi {{name}}, your order #{{order_id}} has shipped!",
  "sender_id": "ShopApp",
  "schedule_mode": "drip",
  "drip_rate": 60
}

Field	Description
`drip_rate`	Messages per minute. Min: `1`, Max: `600`

Example timing

List size	Rate	Duration
300 contacts	60/min	5 minutes
1,000 contacts	100/min	10 minutes
5,000 contacts	200/min	25 minutes

Status

The batch response shows "status": "dripping". The portal shows progress in real time.

Combining modes

You can combine scheduling with drip: schedule the batch to start at a specific time, then drip messages from that point.

{
  "contact_list_ids": [4],
  "text": "Flash sale ends at midnight!",
  "schedule_mode": "scheduled",
  "scheduled_at": "2026-06-01T06:00:00Z",
  "drip_rate": 120
}

This is not yet supported in the current API version. Send the batch with schedule_mode: scheduled first; drip is for immediate dispatch only.

On this page