REST API
Manage contact lists, suppression lists and broadcasts, send transactional email and register webhooks from your own systems. Every plan includes the API.
Base URL and authentication
All methods use this base URL and return JSON:
https://mailhoor.com/api
Authenticate every request with your API key in the X-Auth-APIKey header. Find your key in the portal under Integrations → API & SMTP.
curl -s https://mailhoor.com/api/lists \
-H "X-Auth-APIKey: YOUR_API_KEY"
When you send JSON in the body, set Content-Type: application/json.
Keep your key secret
Your API key can send email and read your contacts. Use it only on your server, never in a website's front-end code or a mobile app. If a key leaks, email support@mailhoor.com right away so we can replace it.
Responses and errors
A successful call returns HTTP 200 (or 201 when something is created). An unsuccessful call returns a standard HTTP error code, such as 400 for invalid input or 401 for a missing or wrong key, and the body explains the error.
Endpoints
Contact lists
| Method | Path | Description |
|---|---|---|
GET |
/lists |
Retrieve all contact lists |
POST |
/lists |
Create a contact list |
GET |
/lists/{id} |
Retrieve a contact list |
PATCH |
/lists/{id} |
Update a contact list |
DELETE |
/lists/{id} |
Delete a contact list |
POST |
/lists/{id}/feed |
Add or update one contact, and tag, untag, unsubscribe or resubscribe it |
POST |
/lists/{id}/add |
Add many contacts as CSV (up to 25 MB per call) |
POST |
/lists/{id}/addunsubs |
Unsubscribe many contacts |
POST |
/lists/{id}/deletecontacts |
Remove contacts by email address |
POST |
/lists/{id}/deletedomains |
Remove contacts matching a set of domains |
GET |
/lists/{id}/domainstats |
Number of contacts per email domain |
POST |
/lists/{id}/export |
Export list data |
GET |
/contactdata/{email} |
Retrieve all data for one contact |
DELETE |
/contactdata/{email} |
Delete all data for one contact |
GET |
/alltags |
List all contact tags |
Suppression and exclusion lists
| Method | Path | Description |
|---|---|---|
GET / POST |
/supplists |
List or create suppression lists |
GET / PATCH / DELETE |
/supplists/{id} |
Retrieve, update or delete a suppression list |
POST |
/supplists/{id}/add |
Add data to a suppression list |
GET |
/exclusion |
Retrieve the exclusion lists |
POST |
/exclusion/{id}/add |
Add data to an exclusion list |
Broadcasts (campaigns)
| Method | Path | Description |
|---|---|---|
GET / POST |
/broadcasts |
List or create broadcasts |
GET / PATCH / DELETE |
/broadcasts/{id} |
Retrieve, update a draft, or delete |
POST |
/broadcasts/{id}/start |
Send a broadcast now |
POST |
/broadcasts/{id}/test |
Send a test email |
POST |
/broadcasts/{id}/cancel |
Cancel a broadcast |
POST |
/broadcasts/{id}/duplicate |
Duplicate a sent or unsent broadcast |
POST |
/broadcasts/{id}/update |
Update a sent broadcast |
POST |
/broadcasts/{id}/export |
Export broadcast data |
GET |
/broadcasts/{id}/domainstats |
Results per receiving domain |
GET |
/broadcasts/{id}/clientstats |
Top devices, browsers and locations |
GET |
/broadcasts/{id}/msgs |
Bounce messages |
Other
| Method | Path | Description |
|---|---|---|
POST |
/transactional/send |
Send a transactional email. See Transactional email |
GET / POST |
/webhooks |
List or create webhooks. See Webhooks |
PATCH / DELETE |
/webhooks/{id} |
Update or delete a webhook |
POST |
/imageupload |
Upload an image |
GET |
/exports |
Retrieve exported files |
GET |
/userroutes |
Available sending routes |
The full machine-readable specification (Swagger 2.0) is at mailhoor.com/openapi.yaml. Import it into Postman or Insomnia to try every method.
Example: add a contact
curl -s -X POST https://mailhoor.com/api/lists/LIST_ID/feed \
-H "X-Auth-APIKey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "sara@example.com", "tags": ["webinar-oct"], "data": {"First Name": "Sara", "City": "Cairo"}}'
Only add people who agreed to receive email from you.