Scheduling Emails

Scheduling lets you queue emails for delivery at a specific future time. This is useful for time-zone-aware sends, coordinated campaigns, and timed transactional emails.

Email scheduling requires the Starter plan or above. Free plan users can only send immediately.

Scheduling via the API

Set the send_at field to an ISO 8601 datetime string on any send or batch request:

curl -X POST https://govconnect.ke/v1/emails/ \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_": {"email": "hello@yourdomain.com", "name": "Your Company"},
    "to": [{"email": "customer@example.com"}],
    "subject": "Your weekly report",
    "html": "<p>Here is your weekly report.</p>",
    "send_at": "2026-06-10T09:00:00Z"
  }'

The response status is scheduled instead of queued:

{
  "id": "3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d",
  "status": "scheduled",
  "message_id": "<...@govconnect.ke>",
  "rejection_reason": null
}

send_at rules

send_at must satisfy all of the following, or the request returns 400 Bad Request:

It must be in the future.
It must be at least 1 minute from now.
It must be no more than 30 days in the future.

Provide send_at in UTC. Convert the recipient's local time to UTC before making the API call.

Scheduling from the composer

Open the dashboard composer.
Fill in the sender, recipients, subject, and body.
Enable scheduling and choose a send time.
Confirm. The email moves to the Scheduled queue.

Listing scheduled emails

GET /v1/emails/scheduled

Returns every scheduled (not yet sent) email, ordered by send time, each with a seconds_until_send countdown:

curl https://govconnect.ke/v1/emails/scheduled \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

[
  {
    "id": "3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d",
    "from_address": "Your Company <hello@yourdomain.com>",
    "to_addresses": ["customer@example.com"],
    "subject": "Your weekly report",
    "status": "scheduled",
    "tags": [],
    "scheduled_at": "2026-06-10T09:00:00+00:00",
    "seconds_until_send": 86400,
    "created_at": "2026-06-09T09:00:00+00:00"
  }
]

In the dashboard, scheduled emails appear in the Email Logs -> Scheduled tab.

Cancelling a scheduled email

DELETE /v1/emails/scheduled/:id

Cancels a scheduled email before it sends. The email moves to cancelled status.

curl -X DELETE https://govconnect.ke/v1/emails/scheduled/3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

{ "id": "3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d", "status": "cancelled" }

Returns 404 Not Found if the email is not in the scheduled queue (for example, it has already sent or was already cancelled).

Sending a scheduled email immediately

POST /v1/emails/scheduled/:id/send-now

Dispatches a scheduled email right away instead of waiting for its send_at time.

curl -X POST https://govconnect.ke/v1/emails/scheduled/3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d/send-now \
  -H "Authorization: Bearer tfm_k_YOUR_API_KEY"

{ "id": "3f8c1e2a-9b4d-4c7e-8a1f-2d6b5e9c0a3d", "status": "queued" }

Returns 404 Not Found if the email is not in the scheduled queue. In the dashboard, both Cancel and Send Now are available from the Scheduled tab.

Scheduling Emails

On this page