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 or Excel (.xlsx) file to bulk-import contacts. The email column is detected automatically; a name column fills the contact name and every other column is stored as metadata (usable as a merge field). Emails already in the list are skipped:
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 '{
"contact_list_id": "{list_id}",
"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"]
}'contact_list_id is required and must match the {list_id} in the URL. sender_address_id is the ID of one of your active sender addresses. Provide html, text or both. Each contact gets an individual email; addresses on your suppression list are not delivered.
{
"queued": 1250,
"skipped": 3,
"errors": []
}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=0&limit=50" \
-H "Authorization: Bearer esms_k_your_api_key"page is zero-based (first page is 0); limit defaults to 50 (maximum 200). Export a list with GET /v1/contacts/{list_id}/export (CSV) and rename it with PATCH /v1/contacts/{list_id}.
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.