API Documentation — TuruMail REST API Reference

Authentication

TuruMail uses API key authentication with Bearer tokens. Every request must include your API key in the Authorization header.

Generate your API key from Dashboard → Settings → API Keys. Keys are prefixed with tm_live_ for production and tm_test_ for testing.

Authentication Header

# Include in every request
Authorization: Bearer tm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Base URL

Base URL https://api.turumail.com/v2

All API endpoints are relative to this base URL. We use semantic versioning — breaking changes increment the major version. The current stable version is v2.

Rate Limits

Plan	Requests/minute	Sends/hour	Batch size
Starter	60	1,000	100
Pro	300	10,000	1,000
Enterprise	1,000	100,000	10,000

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Authentication

POST /api/v1/user/login Get API token using email and password

Get API token using email and password

Parameter	Type	Description
email Required	string	User's email
password Required	string	User's password

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/user/login \
-d email=user@example.com \
-d password=yourpassword

POST /api/v1/login-token Generate one time login token

Generate one time login token

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/login-token \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

LISTS

POST /api/v1/lists New list

New list

Parameter	Type	Description
name Required	string	List's name
from_email Required	string	Default From email address
from_name Required	string	Default From name
divider Required	string	Contact information
contact[company] Required	string	Name
contact[state] Required	string	State / Province / Region
contact[address_1] Required	string	Address 1
contact[address_2] Required	string	Address 2
contact[city] Required	string	City
contact[zip] Required	string	Zip / Postal code
contact[phone] Required	string	Phone
contact[country_id] Required	string	Country id
contact[email] Required	string	Email
contact[url] Optional	string	Home page
subscribe_confirmation Required	string	Send subscription confirmation email (Double Opt-In)
send_welcome_email Required	string	Send a final welcome email
unsubscribe_notification Required	string	Send unsubscribe notification to subscribers
send_welcome_email Required	string	Send a final welcome email

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d name=List+1 \
-d from_email=admin@abccorp.org \
-d from_name=ABC+Corp. \
-d contact[company]=ABC+Corp. \
-d contact[state]=Armagh \
-d contact[address_1]=14+Tottenham+Court+Road+London+England \
-d contact[address_2]=44-46+Morningside+Road+Edinburgh+Scotland+EH10+4BF \
-d contact[city]=Noname \
-d contact[zip]=80000 \
-d contact[phone]=123+456+889 \
-d contact[country_id]=1 \
-d contact[email]=info@abccorp.org \
-d contact[url]=http://www.abccorp.org \
-d subscribe_confirmation=1 \
-d send_welcome_email=1 \
-d unsubscribe_notification=1

GET /api/v1/lists Get information about all lists

Get information about all lists

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/lists/{uid} Get information about a specific list

Get information about a specific list

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

POST /api/v1/lists/{uid}/add-field Add custom field to list

Add custom field to list

Parameter	Type	Description
type Required	string	Choose one of these types: text, number, datetime.
label Required	string	Field' label
tag Required	string	The tag name may have alpha-numeric characters, as well as dashes and underscores.
default_value Optional	string	Default value of the field

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{uid}/add-field \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d type=text \
-d label=Custom \
-d tag=CUSTOM_FIELD_1 \
-d default_value=test

DELETE /api/v1/lists/{uid} Delete a list

Delete a list

Parameter	Type	Description
uid Required	string	List's uid

Example Request

curl -X DELETE -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

CAMPAIGNS

GET /api/v1/campaigns Get information about all campaigns

Get information about all campaigns

Parameter	Type	Description
per_page Optional	string	Number of subscribers per page
page Required	string	Page number

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

POST /api/v1/campaigns Add new campaign

Add new campaign

Parameter	Type	Description
list_uid Required	string	List's uid
name Required	string	New campaign name
subject Required	string	Email subject
from_email Required	string	From email
from_name Required	string	From name
reply_to Required	string	Reply-to email
track_open Optional	string	Track open (true\|false)
track_click Optional	string	Track click (true\|false)
sign_dkim Optional	string	Sign dkim (true\|false)
skip_failed_messages Optional	string	Track open (true\|false)
html Optional	string	Campaign HTML content

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d mail_list_uid={list_uid} \
-d name=MyCampaign \
-d subject=HelloWorld \
-d from_email=noreply@gmail.com \
-d from_name=NoReply \
-d reply_to=noreply@gmail.com \
-d track_open=true \
-d track_click=true \
-d sign_dkim=false \
-d skip_failed_messages=false \
-d html='<p>Hello!</p>'

GET /api/v1/campaigns/{uid} Get information about a specific campaign

Get information about a specific campaign

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

PATCH /api/v1/campaigns/{uid} Update campaign

Update campaign

Parameter	Type	Description
list_uid Required	string	List's uid
name Required	string	Campaign name
subject Required	string	Email subject
from_email Required	string	From email
from_name Required	string	From name
reply_to Required	string	Reply-to email
track_open Optional	string	Track open (true\|false)
track_click Optional	string	Track click (true\|false)
sign_dkim Optional	string	Sign dkim (true\|false)
skip_failed_messages Optional	string	Track open (true\|false)

Example Request

curl -X PATCH -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d name=MyCampaign2 \
-d subject=HelloWorld2 \
-d sign_dkim=true

POST /api/v1/campaigns/{uid}/run Run a specific campaign

Run a specific campaign

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/run \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

POST /api/v1/campaigns/{uid}/pause Pause a specific campaign

Pause a specific campaign

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/pause \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

POST /api/v1/campaigns/{uid}/resume Resume a specific campaign

Resume a specific campaign

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/resume \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

DELETE /api/v1/campaigns/{uid} Delete a campaign

Delete a campaign

Parameter	Type	Description
uid Required	string	Campaign's uid

Example Request

curl -X DELETE -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/campaigns/{uid}/tracking-log/download Download campaign tracking log

Download campaign tracking log

Parameter	Type	Description
format Required	string	Log format (default: CSV)

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/tracking-log/download \
-d type=csv \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/campaigns/{uid}/open-log/download Download campaign open log

Download campaign open log

Parameter	Type	Description
format Required	string	Log format (default: CSV)

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/open-log/download \
-d type=csv \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/campaigns/{uid}/click-log/download Download campaign click log

Download campaign click log

Parameter	Type	Description
format Required	string	Log format (default: CSV)

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/click-log/download \
-d type=csv \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/campaigns/{uid}/bounce-log/download Download campaign bounce log

Download campaign bounce log

Parameter	Type	Description
format Required	string	Log format (default: CSV)

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/bounce-log/download \
-d type=csv \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/campaigns/{uid}/feedback-log/download Download campaign feedback log

Download campaign feedback log

Parameter	Type	Description
format Required	string	Log format (default: CSV)

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/feedback-log/download \
-d type=csv \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

GET /api/v1/campaigns/{uid}/unsubscribe-log/download Download campaign unsubscribe log

Download campaign unsubscribe log

Parameter	Type	Description
format Required	string	Log format (default: CSV)

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/campaigns/{uid}/unsubscribe-log/download \
-d type=csv \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

SUBSCRIBERS

GET /api/v1/subscribers Display list's subscribers

Display list's subscribers

Parameter	Type	Description
list_uid Required	string	List's uid
open Optional	string	yes - opened some campaigns no - not opened any campaign
click Optional	string	yes - clicked some campaigns no - not clicked any campaign
per_page Optional	string	Number of subscribers per page
page Required	string	Page number

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d list_uid={list_uid} \
-d per_page=20 \
-d page=1

POST /api/v1/subscribers Create subscriber for a mail list

Create subscriber for a mail list

Parameter	Type	Description
list_uid Required	string	List's uid
EMAIL Required	string	Subscriber's email
tag Optional	string	Subscriber's tags, seperated by a comma (,).
status Optional	string	Subscriber's status: subscribed \| unsubscribed \| unconfirmed
[OTHER_FIELDS...] Optional	string	All subscriber's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the list fields configuration)

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d list_uid={list_uid} \
-d EMAIL=test@gmail.com \
-d tag=foo,bar,tag+with+space, \
-d FIRST_NAME=Marine \
-d LAST_NAME=Joze \
-d status=subscribed

GET /api/v1/subscribers/{id} Get information about a specific subscriber

Get information about a specific subscriber

Parameter	Type	Description
id Required	string	Subsciber's id or email

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers/{id} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

PATCH /api/v1/subscribers/{id} Update subscriber for a mail list

Update subscriber for a mail list

Parameter	Type	Description
uid Required	string	Subscriber's uid
EMAIL Required	string	Subscriber's email
tag Optional	string	Subscriber's tags, seperated by a comma (,).
[OTHER_FIELDS...] Optional	string	All subscriber's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the list fields configuration)

Example Request

curl -X PATCH -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers/{id} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d EMAIL=test@gmail.com \
-d tag=foo,bar,tag+with+space, \
-d FIRST_NAME=Marine \
-d LAST_NAME=Joze \
-d status=unsubscribed

POST /api/v1/subscribers/{id}/add-tag Add tag(s) to subscriber

Add tag(s) to subscriber

Parameter	Type	Description
tag Optional	string	Subscriber's tags, seperated by a comma (,).

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers/-ID-/add-tag \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d tag=foo,bar,tag+with+space

POST /api/v1/subscribers/{id}/remove-tag Remove tag(s) to subscriber

Remove tag(s) to subscriber

Parameter	Type	Description
tag Optional	string	Subscriber's tags, seperated by a comma (,).

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers/-ID-/remove-tag \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d tag=foo,bar,tag+with+space

GET /api/v1/subscribers/email/{email} Find subscribers with email

Find subscribers with email

Parameter	Type	Description
email Required	string	Subsciber's email

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers/email/{email} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

PATCH /api/v1/lists/{list_uid}/subscribers/{id}/subscribe Subscribe a subscriber

Subscribe a subscriber

Parameter	Type	Description
list_uid Required	string	List's uid
id Required	string	Subsciber's id

Example Request

curl -X PATCH -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{list_uid}/subscribers/{id}/subscribe \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

PATCH /api/v1/lists/{list_uid}/subscribers/{id}/unsubscribe Unsubscribe a subscriber

Unsubscribe a subscriber

Parameter	Type	Description
list_uid Required	string	List's uid
id Required	string	Subsciber's id

Example Request

curl -X PATCH -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{list_uid}/subscribers/{id}/unsubscribe \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

PATCH /api/v1/lists/{list_uid}/subscribers/email/{email}/unsubscribe Unsubscribe a subscriber by email

Unsubscribe a subscriber by email

Parameter	Type	Description
list_uid Required	string	List's uid
email Required	string	Subsciber's email

Example Request

curl -X PATCH -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{list_uid}/subscribers/email/{email}/unsubscribe \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

DELETE /api/v1/subscribers/{id} Delete a subscriber

Delete a subscriber

Parameter	Type	Description
list_uid Required	string	List's uid
id Required	string	Subsciber's id

Example Request

curl -X DELETE -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/subscribers/{id} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

POST /api/v1/lists/{list_uid}/subscribers/bulk Bulk import subscribers (synchronous — applied inline, returns per-row results)

Bulk import subscribers (synchronous — applied inline, returns per-row results)

Parameter	Type	Description
list_uid Required	string	List's uid
subscribers Required	string	Array of subscriber objects, each with EMAIL (required) and any custom field tags (FIRST_NAME, LAST_NAME, ...). Each row may also include $tags (array of tag names) and $status (subscribed \| unsubscribed \| unconfirmed)
mode Optional	string	Duplicate-handling strategy: overwrite \| skip
overwrite_status Optional	string	When mode=overwrite, also overwrite existing subscriber's status
overwrite_tags Optional	string	When mode=overwrite, replace existing tags instead of merging

Example Request

curl -X POST \
-H "accept:application/json" \
-H "Content-Type: application/json" \
"https://mailer.turumail.com/api/v1/lists/{list_uid}/subscribers/bulk?api_token=tm_live_xxxxxxxxxxxxxxxx" \
-d '{
  "mode": "overwrite",
  "overwrite_status": false,
  "overwrite_tags": false,
  "subscribers": [
    {"EMAIL": "alice@example.com", "FIRST_NAME": "Alice", "tags": ["vip","newsletter"]},
    {"EMAIL": "bob@example.com",   "FIRST_NAME": "Bob",   "status": "subscribed"}
  ]
}'

POST /api/v1/lists/{list_uid}/subscribers/bulk/async Bulk import subscribers (asynchronous — queued; poll status via /api/v1/import-jobs/{job_uid}). Accepts either a JSON payload (same shape as the sync endpoint) or a multipart CSV upload.

Bulk import subscribers (asynchronous — queued; poll status via /api/v1/import-jobs/{job_uid}). Accepts either a JSON payload (same shape as the sync endpoint) or a multipart CSV upload.

Parameter	Type	Description
list_uid Required	string	List's uid
subscribers Optional	string	JSON variant: array of subscriber objects (same shape as the sync endpoint)
file Optional	string	Multipart variant: CSV file upload
mapping Optional	string	Multipart variant: JSON object mapping CSV header → field tag (e.g. {"Email":"EMAIL","First":"FIRST_NAME"}). Numeric field ids also accepted.
mode Optional	string	Duplicate-handling strategy: overwrite \| skip
overwrite_status Optional	string	When mode=overwrite, also overwrite existing subscriber's status
overwrite_tags Optional	string	When mode=overwrite, replace existing tags instead of merging

Example Request

# JSON variant
curl -X POST \
-H "accept:application/json" \
-H "Content-Type: application/json" \
"https://mailer.turumail.com/api/v1/lists/{list_uid}/subscribers/bulk/async?api_token=tm_live_xxxxxxxxxxxxxxxx" \
-d '{"mode":"overwrite","subscribers":[{"EMAIL":"alice@example.com"},{"EMAIL":"bob@example.com"}]}'

# CSV multipart variant
curl -X POST \
-H "accept:application/json" \
"https://mailer.turumail.com/api/v1/lists/{list_uid}/subscribers/bulk/async?api_token=tm_live_xxxxxxxxxxxxxxxx" \
-F "file=@/path/to/subscribers.csv" \
-F 'mapping={"Email":"EMAIL","First Name":"FIRST_NAME"}' \
-F "mode=overwrite"

GET /api/v1/lists/{list_uid}/import-jobs List recent bulk-import jobs for a list

List recent bulk-import jobs for a list

Parameter	Type	Description
list_uid Required	string	List's uid
limit Optional	string	Max number of jobs to return

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/lists/{list_uid}/import-jobs \
-d api_token=tm_live_xxxxxxxxxxxxxxxx \
-d limit=20

GET /api/v1/import-jobs/{job_uid} Poll a bulk-import job — status, progress, counts

Poll a bulk-import job — status, progress, counts

Parameter	Type	Description
job_uid Required	string	Job uid returned by the async endpoint

Example Request

curl -X GET -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/import-jobs/{job_uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

DELETE /api/v1/import-jobs/{job_uid} Cancel a queued or running bulk-import job (soft cancel — job_uid stays queryable, status becomes "cancelled")

Cancel a queued or running bulk-import job (soft cancel — job_uid stays queryable, status becomes "cancelled")

Parameter	Type	Description
job_uid Required	string	Job uid returned by the async endpoint

Example Request

curl -X DELETE -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/import-jobs/{job_uid} \
-d api_token=tm_live_xxxxxxxxxxxxxxxx

Notification

POST /api/v1/notification/bounce Send a HARD bounce to the application. Notice that it is not needed to inform the application of SOFT bounces

Send a HARD bounce to the application. Notice that it is not needed to inform the application of SOFT bounces

Parameter	Type	Description
message_id Required	string	Message's id
description Required	string	Notification message

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/notification/bounce \
-d api_token=tm_live_xxxxxxxxxxxxxxxx  \
-d message_id=201637442604422402.6199642caf7f3@example.com

Feedback Loop

POST /api/v1/notification/feedback Send a bounce or abuse report to the application. It could be a success / bounce / feedback or abuse report

Send a bounce or abuse report to the application. It could be a success / bounce / feedback or abuse report

Parameter	Type	Description
message_id Required	string	Message's id
type Required	string	Poassible values include: spam \| abuse
description Required	string	Notification message

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/notification/feedback \
-d api_token=tm_live_xxxxxxxxxxxxxxxx  \
-d message_id=201637442604422402.6199642caf7f3@example.com  \
-d type=abuse

FILE

POST /api/v1/file/upload Upload file(s) to customer's storage

Upload file(s) to customer's storage

Parameter	Type	Description
file_url Required	string	File url
subdirectory Optional	string	Custom subdirectory

Example Request

curl -X POST -H "accept:application/json" -G \
https://mailer.turumail.com/api/v1/file/upload \
-d api_token=tm_live_xxxxxxxxxxxxxxxx  \
-d files='[{"url":"http://example.com/images/logo_big.svg","subdirectory":"path/to/file"},{"url":"http://example.com/images/logo_big.svg","subdirectory":"path/to/file2"}]'

Webhook Events

TuruMail can send real-time webhook notifications to your endpoint for these events:

email.delivered — Email successfully delivered to the recipient's mail server
email.opened — Recipient opened the email (pixel tracking)
email.clicked — Recipient clicked a tracked link
email.replied — Recipient replied to your email
email.bounced — Email bounced (includes hard/soft bounce type)
email.spam_complaint — Recipient reported email as spam
email.unsubscribed — Recipient clicked the unsubscribe link
blacklist.detected — Your sending IP was detected on a blacklist
warmup.limit_reached — Daily warmup volume limit reached for an IP

All webhooks are signed with an HMAC-SHA256 signature in the X-TuruMail-Signature header for verification.

TuruMail REST APIReference

Authentication

Base URL

Rate Limits

Authentication

LISTS

CAMPAIGNS

SUBSCRIBERS

Notification

Feedback Loop

FILE

Webhook Events

Get Your API Key

TuruMail REST API
Reference