DEVELOPER RESOURCES

HudHud SMS API

Send, schedule, track, and manage SMS through a secure REST API built for Ethiopian and international messaging workflows.

First-party Base URL: https://cloud.hudhudexpress.com/api

Portal-generated hh_live_... keys work on HudHud Cloud first-party routes only. Do not send them to the legacy provider endpoint at sms.hudhudcloud.com/api/v3.

Authentication

Use a server-side environment variable such as $HUDHUD_SMS_API_TOKEN. Never place a live token in frontend JavaScript, source control, screenshots, or logs.

Keys created in the HudHud Cloud portal begin with hh_live_ and authenticate the first-party route https://cloud.hudhudexpress.com/api/sms/send using either Authorization: Bearer hh_live_... or X-API-Key: hh_live_.... They are not upstream Kannel credentials and should not be sent directly to the provider endpoint.

Authorization: Bearer $HUDHUD_SMS_API_TOKEN
Accept: application/json
Content-Type: application/json

HudHud Cloud client portal API

The client portal at https://cloud.hudhudexpress.com/sms.html uses first-party routes under /api/sms. These routes are separate from the upstream provider API under https://sms.hudhudcloud.com/api/v3.

OperationMethodRoute
Quote segments and costPOST/api/sms/quote
Load workspaceGET/api/sms/workspace
Validate Excel/CSV recipientsPOST/api/sms/campaigns/import
Create campaign draftPOST/api/sms/campaigns
Request campaign sendPOST/api/sms/campaigns/:id/send — returns sent percentage and delivery counts
Create developer keyPOST/api/sms/api-keys
Send one SMSPOST/api/sms/send

Bulk uploads accept .xlsx, .xls, .csv, and .tsv files up to 2 MB and 10,000 recipients. Recognized columns include recipient, phone, mobile, number, telephone, and to. The response reports valid rows, invalid rows, duplicate count, and valid percentage. Portal campaign sending requires explicit confirmation and remains disabled by the production safety gate until deliberately enabled.

Send SMS

POST/api/sms/send or /api/v3/sms/send

Use a portal-generated API key with the first-party HudHud Cloud endpoint. Both X-API-Key and Authorization: Bearer are accepted. The v3 alias accepts both the concise portal fields and the provider-style aliases.

FieldRequiredDescription
to or recipientYesOne Ethiopian international number in 2519XXXXXXXX format.
text or messageYesMessage body.
sender or sender_idNoSender ID. Trial accounts use the configured trial sender automatically.
languageNoUse en or am; defaults to English for type: plain.
curl -X POST 'https://cloud.hudhudexpress.com/api/sms/send' \\
  -H 'X-API-Key: hh_live_REPLACE_WITH_NEW_KEY' \\
  -H 'Accept: application/json' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "to": "2519XXXXXXXX",
    "text": "Your HudHud Cloud verification code is 123456.",
    "sender": "7114",
    "language": "en"
  }'

Compatibility example: The same key and body may be sent to https://cloud.hudhudexpress.com/api/v3/sms/send using recipient, message, sender_id, and type: plain.

Campaigns

POST/sms/campaign

Send to a provider contact list with contact_list_id, sender_id, type, and message. HudHud Cloud campaign execution is confirmation-gated, quota-limited, rate-limited, and disabled until live credentials and an approved test destination are available.

Messages and status

GET/sms/{uid} retrieves one message.

GET/sms/ lists messages. Supported filters include start_date, end_date, sms_type, direction, and timezone.

curl -G 'https://sms.hudhudcloud.com/api/v3/sms/' \\
  -H "Authorization: Bearer $HUDHUD_SMS_API_TOKEN" \\
  --data-urlencode 'start_date=2026-09-01 00:00:00' \\
  --data-urlencode 'end_date=2026-09-30 23:59:59' \\
  --data-urlencode 'timezone=Africa/Addis_Ababa'

Segmentation and pricing

English messages use 160 characters per single segment. Amharic messages use 70 characters per single segment. Multipart thresholds are 153 and 67 when configured. Trial SMS uses sender 7114 and is capped at 50 segments.

Integration safety

Validate recipients and message length on the server, persist provider IDs and delivery states, and use bounded retries only for safe read operations. Never retry a send after an ambiguous timeout until message status has been checked. Rotate any token that has appeared in a screenshot or pasted document.