eSMS AfricaeSMS Africa
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 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,Charlie

Response:

{
  "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:

VariableDescription
{{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.

On this page