Developer API

Send transactional and bulk email and read your usage programmatically over a simple REST API.

Base URL

All endpoints below are relative to this base.

https://api.nhume.co.zw/api/v1

Authentication

Every request must include your API key, either as a Bearer token or an X-Api-Key header. Create and revoke keys on the API keys page — the secret is shown only once.

curl https://api.nhume.co.zw/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

# or, equivalently:
curl https://api.nhume.co.zw/api/v1/usage \
  -H "X-Api-Key: YOUR_API_KEY"

Keep your key secret

Call the API from your server only — never embed your key in client-side code.

Endpoints

POST/send

Send a single transactional email.

Body parameters

from	required	A verified sender address.
from_name	optional	Display name for the sender.
reply_to	optional	Reply-to address.
to	required	Recipient email address.
to_name	optional	Recipient display name.
subject	required	Email subject line.
html	required	HTML body.
text	optional	Plain-text body.

Request

curl -X POST https://api.nhume.co.zw/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "sender@yourdomain.com",
  "to": "customer@example.com",
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>"
}'

Response

{
  "data": {
    "id": "9b1c0d2e-...",
    "status": "QUEUED",
    "to": "customer@example.com",
    "subject": "Your receipt"
  },
  "message": "Message accepted for delivery."
}

POST/send/bulk

Send the same email to many recipients (up to 1,000) in one request.

Body parameters

from	required	A verified sender address.
subject	required	Email subject line.
html	required	HTML body sent to all recipients.
text	optional	Plain-text body.
recipients	required	Array of { to, to_name? } objects.

Request

curl -X POST https://api.nhume.co.zw/api/v1/send/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "sender@yourdomain.com",
  "subject": "Monthly newsletter",
  "html": "<p>Hello!</p>",
  "recipients": [
    { "to": "ada@example.com", "to_name": "Ada" },
    { "to": "grace@example.com" }
  ]
}'

Response

{
  "data": [
    { "id": "...", "status": "QUEUED", "to": "ada@example.com" },
    { "id": "...", "status": "QUEUED", "to": "grace@example.com" }
  ],
  "accepted": 2,
  "message": "2 messages accepted for delivery."
}

GET/usage

Read your current plan, billing period and per-type credit consumption.

Request

curl https://api.nhume.co.zw/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "plan": "Starter",
    "period_start": "2026-06-01T00:00:00+00:00",
    "period_end": "2026-07-01T00:00:00+00:00",
    "credits": [
      { "type": "TRANSACTIONAL", "allowance": 1000, "used": 240, "remaining": 760, "overage": 0 },
      { "type": "MARKETING", "allowance": 5000, "used": 0, "remaining": 5000, "overage": 0 }
    ]
  }
}

GET/messages/{id}

Fetch the delivery status of a message you sent.

Request

curl https://api.nhume.co.zw/api/v1/messages/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "9b1c0d2e-...",
    "status": "SENT",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "provider_message_id": "0100018f...",
    "error": null,
    "sent_at": "2026-06-19T10:24:11+00:00"
  }
}

Good to know

The from address must be a verified sender. Set one up on the Subscriptions page.
Sends are queued and delivered asynchronously — poll GET /messages/{id} for the final status.
Each delivered email consumes one transactional credit. Going over your allowance is allowed and billed as overage.
Bulk sends accept up to 1,000 recipients per request; each becomes its own trackable message.
If your organisation is suspended for an unpaid invoice, the API returns 403 until you settle it.