eSMS Mail
Contacts & Bulk Send
Manage contact lists and send bulk emails.
Contact lists let you organize recipients and send bulk emails to entire lists at once.
Create a contact list
curl -X POST https://send.esmsafrica.io/v1/contacts/ \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name": "Newsletter subscribers", "description": "Monthly newsletter recipients"}'Add contacts
Single contact
curl -X POST https://send.esmsafrica.io/v1/contacts/{list_id}/contacts \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "name": "John Doe", "metadata": {"company": "Acme"}}'CSV import
Upload a CSV file to bulk-import contacts:
curl -X POST https://send.esmsafrica.io/v1/contacts/{list_id}/upload \
-H "Authorization: Bearer esms_k_your_api_key" \
-F "file=@contacts.csv"CSV format:
email,name
user1@example.com,Alice
user2@example.com,Bob
user3@example.com,CharlieResponse:
{
"imported": 3,
"skipped": 0,
"errors": []
}Send to a contact list
Send a bulk email to all contacts in a list:
curl -X POST https://send.esmsafrica.io/v1/contacts/{list_id}/send \
-H "Authorization: Bearer esms_k_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"sender_address_id": "your_sender_id",
"subject": "Monthly newsletter — January",
"html": "<h1>Hello {{name}}!</h1><p>Here are this month updates...</p>",
"tags": ["newsletter", "january"]
}'Template variables
Use double curly braces to personalize emails:
| Variable | Description |
|---|---|
{{email}} | Contact's email address |
{{name}} | Contact's name |
{{metadata_key}} | Any metadata field (e.g. {{company}}) |
Managing lists
List all contact lists
curl https://send.esmsafrica.io/v1/contacts/ \
-H "Authorization: Bearer esms_k_your_api_key"Get contacts in a list
curl "https://send.esmsafrica.io/v1/contacts/{list_id}?page=1&limit=50" \
-H "Authorization: Bearer esms_k_your_api_key"Delete a contact
curl -X DELETE https://send.esmsafrica.io/v1/contacts/{list_id}/contacts/{contact_id} \
-H "Authorization: Bearer esms_k_your_api_key"Delete a list
curl -X DELETE https://send.esmsafrica.io/v1/contacts/{list_id} \
-H "Authorization: Bearer esms_k_your_api_key"This permanently deletes the list and all its contacts.