Send transactional email
Receipts, alerts and codes by email, with bounces handled for you.
Email is for transactional messages: receipts, notifications, codes, account alerts. It needs approval first; see Sending access. Promotional email isn't offered.
Send an email
curl https://api.softlinksms.co.ke/api/v1/email \
-H "X-Api-Key: $SOFTLINK_API_KEY" \
-H "Idempotency-Key: receipt-INV-2026-0042" \
-H "Content-Type: application/json" \
-d '{
"recipients": ["jane@example.com"],
"subject": "Your receipt for INV-2026-0042",
"body": "<p>Hi Jane,</p><p>We received your payment of <strong>KES 1,500</strong>. Thank you!</p>"
}'| Field | Rules |
|---|---|
recipients | 1–1,000 email addresses. Each gets its own copy, with no other recipients visible. |
subject | Up to 255 characters. |
body | HTML. Inline styles render most reliably across email clients. |
traffic_class | Optional. Always transactional. |
The response is 201 with the send's batch_id, total_price, and a messages list with one email per recipient, each starting as pending.
Bounces and the suppression list
When an address hard-bounces, its owner marks your email as spam, or they unsubscribe, we add the address to a suppression list and stop sending to it. This protects your sender reputation and everyone else's.
A send that includes a suppressed address is rejected with 400, naming the addresses:
{
"error": {
"code": "invalid",
"message": "Recipients suppressed due to a prior bounce, complaint or unsubscribe: old@example.com",
"details": {
"non_field_errors": [
"Recipients suppressed due to a prior bounce, complaint or unsubscribe: old@example.com"
]
}
}
}Remove those addresses and send again. To get an address off the list, for example after a customer fixes their mailbox, contact support@softlinksms.co.ke.
Track the outcome
| Webhook event | When |
|---|---|
email.delivered | The recipient's mail server accepted the email, or the recipient opened it. |
email.bounced | The address doesn't exist or won't accept mail. It's now suppressed. |
email.failed | We couldn't hand the email to the mail system. The cost is refunded. |
Soft bounces (a full mailbox, a temporary server error) are retried automatically and don't produce an event until the final outcome.
Delivered isn't read
email.delivered means the receiving server accepted the email. It may still land in a spam folder. Keep your content clearly transactional, and avoid link shorteners and image-only emails.