| Property | Value |
|---|---|
| Base URL | https://app.maxmailhq.com/ |
| Authentication | API Key (passed as api_key parameter) |
| Response Formats | JSON (format=json) or XML (format=xml, default) |
| HTTP Method | All endpoints accept both GET and POST |
| Content-Type (JSON) | application/json; charset=utf-8 |
| Content-Type (XML) | text/xml; charset=utf-8 |
All endpoints require an api_key parameter matching the account's stored API key in the global database.
Parameters used for auth:
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Unique API key for the account |
user_email |
string | Optional | If provided, it is validated against the account's email |
format |
string | Optional | json or xml (default: xml; some endpoints default to json) |
| Code | Meaning |
|---|---|
| 200 | Success / OK |
| 100 | Mailing list not found |
| 101 | Subscriber already exists (duplicate) |
| 103 | Subscriber validation error |
| 104 | Custom field validation error |
| 105 | General subscriber error |
| 106 | List creation/update failed |
| 107 | Reply-to email domain mismatch (must match account domain) |
| 110 | Campaign creation failed |
| 111 | Campaign send scheduling failed |
| 112 | Campaign not ready to send (wrong status) |
| 113 | Campaign not found |
| 115 | Campaign cannot be edited (already sent/scheduled) |
| 116 | Email address is required |
| 118 | HTML content or template ID is required |
| 120 | Survey not found |
| 121 | Survey response error |
| 122 | From address is required for custom HTML |
| 123 | Invalid date format |
| 124 | Endpoint deprecated |
| 125 | date_range parameter is required |
| 126 | date parameter is required |
| 300 | Generic error |
| 400 | Invalid API key or user email mismatch |
| 401 | Missing required parameters |
| 777 | No sending credits available / Invalid from address |
JSON:
{
"success": "false",
"error": 400,
"error_msg": "Invalid API Key"
}
XML:
<?xml version="1.0"?>
<ApiResponse>
<success>false</success>
<error code="400">Invalid API Key</error>
</ApiResponse>
Sends a single transactional email to one recipient. Requires available sending credits.
GET / POST/api/transactional.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
email |
string | Yes | Recipient email address |
subject |
string | Yes | Email subject line |
html |
string | Conditional | Raw HTML content (URL-encoded). Required if template_id not provided |
template_id |
integer | Conditional | ID of a stored transactional template. Required if html not provided |
from_address |
string | Conditional | Sender email address. Required when html is provided |
from_name |
string | Optional | Sender display name |
fname |
string | Optional | Recipient first name |
lname |
string | Optional | Recipient last name |
comp |
string | Optional | Recipient company name |
mob |
string | Optional | Recipient mobile number |
city |
string | Optional | Recipient city |
ctry |
string | Optional | Recipient country |
gender |
string | Optional | Recipient gender (male / female) |
age |
integer | Optional | Recipient age |
format |
string | Optional | Response format: json or xml (default: xml) |
cf_* |
mixed | Optional | Custom field values (e.g., cf_5=value) |
{
"success": "true",
"error": 200,
"error_msg": "OK"
}
{
"success": "false",
"error": 777,
"error_msg": "No credits available."
}
Specific error codes for this endpoint:
116 — Email address missing118 — Neither html nor template_id provided122 — from_address required when using custom html777 — No sending credits remainingSubscribes an email address to a mailing list. Handles both new subscriptions and updates to existing subscribers.
GET / POST/api/subscription.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
mailing_list |
integer | Yes | Mailing list ID to subscribe to |
email |
string | Yes | Subscriber email address |
fname |
string | Optional | First name |
lname |
string | Optional | Last name |
comp |
string | Optional | Company |
mob |
string | Optional | Mobile number |
city |
string | Optional | City |
country |
string | Optional | Country |
gender |
string | Optional | Gender |
age |
integer | Optional | Age |
flang |
string | Optional | Form language code (defaults to account language) |
format |
string | Optional | json or xml (default: xml) |
cf_* |
mixed | Optional | Custom field values keyed by cf_{id} |
{
"success": "true",
"error": 200,
"error_msg": "OK"
}
Specific error codes for this endpoint:
100 — Mailing list not found101 — Subscriber already exists (duplicate)103 — Subscriber validation error104 — Custom field validation errorUnsubscribes an email address from a mailing list (or all lists based on account unsub_mode setting).
GET / POST/api/unsubscribe.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
email |
string | Yes | Email address to unsubscribe |
mailing_list |
integer | Optional | If provided, unsubscribes from that list only. If 0 or omitted + account mode is "all", unsubscribes from all lists |
campaign_id |
integer | Optional | Associated campaign ID (for tracking) |
unsub_reason |
string | Optional | Reason for unsubscribing |
format |
string | Optional | json or xml (default: xml) |
{
"success": "true",
"error": 200,
"error_msg": "OK"
}
Looks up all mailing lists a given email address is subscribed to and returns their statuses.
GET / POST/api/searchSubscriber.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
email |
string | Yes | Email address to search for |
format |
string | Optional | json or xml (default: xml) |
{
"success": "true",
"error": "200",
"error_msg": "OK",
"SubscriberEmail": "john@example.com",
"SubscribedList": {
"12": {
"MailingListName": "Newsletter",
"Status": "Active"
},
"17": {
"MailingListName": "Promotions",
"Status": "Unsubscribe"
}
}
}
Subscriber status values: Active, Unsubscribe, Bounce
Returns all subscribers belonging to a specific mailing list, including any custom field values.
GET/api/fetchSubscribers.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
email |
string | Yes | (Used as auth hint; actual filter is mailing_list_id) |
mailing_list_id |
integer | Yes | Mailing list ID to fetch subscribers from |
{
"success": "true",
"error": "200",
"error_msg": "OK",
"SubscribedList": [
{
"mc_id": 1,
"mc_fname": "John",
"mc_lname": "Doe",
"mc_email": "john@example.com",
"mc_mob": "0400000000",
"mc_status": "Active",
"cf_3_value": "Sydney",
"cf_3_label": "City Preference"
}
]
}
Retrieves full profile details for a single subscriber within a mailing list.
GET / POST/api/getSubscriberDetails.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
mailing_list |
integer | Yes | Mailing list ID the subscriber belongs to |
subscriber_id |
integer | Conditional | Subscriber's numeric ID. Required if subscriber_email not provided |
subscriber_email |
string | Conditional | Subscriber email. Used if subscriber_id not provided |
format |
string | Optional | json or xml |
{
"success": "true",
"error": "200",
"error_msg": "OK",
"Subscriber": {
"id": 42,
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"mobile": "0400111222",
"company": "Acme Corp",
"age": "30",
"gender": "female",
"city": "Melbourne",
"country": "Australia",
"status": "Active",
"cf_1": "value1"
}
}
Creates a new mailing list under the authenticated account.
GET / POST/api/createList.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
list_name |
string | Yes | Name of the new mailing list |
list_from_name |
string | Optional | Display name for outgoing emails from this list |
list_reply_to_email |
string | Optional | Reply-to email (must share domain with account email) |
list_notify_email |
string | Optional | Email to notify on subscription events |
list_notify_subs |
string | Optional | y / n — notify on new subscriptions |
list_notify_unsubs |
string | Optional | y / n — notify on unsubscriptions |
format |
string | Optional | json or xml |
{
"success": "true",
"error": 200,
"error_msg": "OK",
"mailing_list_id": 55,
"glid": 123
}
Specific error codes:
106 — List creation failed107 — Reply-to email domain does not match account domainUpdates properties of an existing mailing list.
GET / POST/api/editList.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
mailing_list |
integer | Yes | Mailing list ID to edit |
list_name |
string | Optional | New name |
list_from_name |
string | Optional | New sender display name |
list_reply_to_email |
string | Optional | New reply-to email (same domain restriction applies) |
list_notify_email |
string | Optional | New notification email |
list_notify_subs |
string | Optional | y / n |
list_notify_unsubs |
string | Optional | y / n |
format |
string | Optional | json or xml |
{
"success": "true",
"error": 200,
"error_msg": "OK",
"mailing_list_id": 55
}
Retrieves details of one or all mailing lists for the account.
GET / POST/api/getMailingLists.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
mailing_list |
integer | Optional | If provided, returns details for that specific list only. Omit to get all lists |
format |
string | Optional | json or xml |
{
"success": "true",
"error": "200",
"error_msg": "OK",
"glid": "123",
"status": "Active",
"MailingLists": {
"55": {
"feedid": "feed_abc",
"owner": "Acme Co",
"name": "Newsletter",
"email": "newsletter@acme.com",
"subs": "subscribed@acme.com",
"unsubs": "unsubscribed@acme.com",
"status": "Active",
"fields": {
"mc_fname": { "type": "Text Field" },
"cf_3": { "label": "City", "mandatory": "no", "type": "Text Field" }
},
"public_fields": {},
"formtitle": "Subscribe to our Newsletter",
"successurl": "https://acme.com/thanks",
"failurl": "https://acme.com/error",
"notify_email": "admin@acme.com",
"notify_subs": "y",
"notify_unsubs": "y",
"total": 1540,
"bounces": 12,
"optouts": 30
}
}
}
Returns subscriber analytics for a mailing list within a date range. Supports breakdown by email provider, subscription date, source, age group, gender, city, and country.
GET / POST/api/getListAnalytics.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
mailing_list |
integer | Yes | Mailing list ID |
date |
string | Yes | Start date in account's configured date format |
date_range |
string | Yes | day, week, month, or all |
email_provider |
string | Optional | true to include email provider breakdown |
sub_date |
string | Optional | true to include subscription date breakdown |
sub_status |
string | Optional | true to include status breakdown |
sub_source |
string | Optional | true to include source breakdown |
age_group |
string | Optional | true to include age group breakdown |
gender |
string | Optional | true to include gender breakdown |
city |
string | Optional | true to include city breakdown |
country |
string | Optional | true to include country breakdown |
all_fields |
string | Optional | true to include all available breakdowns |
format |
string | Optional | json or xml |
Specific error codes:
123 — Invalid date format125 — date_range is required126 — date is requiredReturns a list of bounced subscribers for a mailing list.
GET / POST/api/getListBounceAnalytics.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
mailing_list |
integer | Yes | Mailing list ID |
format |
string | Optional | json or xml |
Returns an object keyed by subscriber ID containing full subscriber data plus bounce details:
{
"success": "true",
"error": "200",
"error_msg": "OK",
"42": {
"firstname": "John",
"lastname": "Doe",
"email": "john@example.com",
"mobile": "",
"company": "",
"city": "Sydney",
"country": "Australia",
"gender": "male",
"age": "35",
"status": "Bounce",
"date": "2024-01-15",
"last_modified": "2024-01-16",
"source": "import",
"fail_type": "HardBounce",
"fail_message": "550 No such user",
"originator": "",
"external_id": "",
"import": "1",
"responder": "0",
"dupicate": "0"
}
}
Creates a new email campaign in waiting to send status (not yet scheduled).
GET / POST/api/newCampaign.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_name |
string | Yes | Campaign display name |
campaign_subject |
string | Yes | Email subject line |
campaign_list_ids |
string | Yes | Comma-separated mailing list IDs (e.g., "5,12,17") |
campaign_content |
string | Yes | HTML email body content |
campaign_from_name |
string | Optional | Sender display name (defaults to account company name) |
campaign_from_address |
string | Optional | Sender email address. Must be valid RFC email. Defaults to account email |
campaign_header |
string | Optional | HTML header snippet |
campaign_footer |
string | Optional | HTML footer snippet |
campaign_mc_ids |
string | Optional | Comma-separated mailing content IDs for dynamic content |
format |
string | Optional | json or xml |
{
"success": "true",
"error": 200,
"error_msg": "OK",
"campaign_id": 88
}
Specific error codes:
100 — One or more mailing list IDs not found110 — Campaign creation failed (database error)777 — Invalid from addressUpdates a campaign's properties. Only campaigns in waiting to send status can be edited.
GET / POST/api/editCampaign.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_id |
integer | Yes | ID of the campaign to edit |
campaign_list_ids |
string | Optional | New comma-separated mailing list IDs |
campaign_subject |
string | Optional | New subject |
campaign_content |
string | Optional | New HTML content |
campaign_header |
string | Optional | New header |
campaign_footer |
string | Optional | New footer |
campaign_name |
string | Optional | New campaign name |
format |
string | Optional | json or xml |
{
"success": "true",
"error": 200,
"error_msg": "OK",
"campaign_id": 88
}
Specific error codes:
100 — Mailing list not found110 — Campaign update failed115 — Campaign cannot be edited (already sent or scheduled)Schedules or immediately sends a campaign that is in waiting to send status. Requires available credits.
GET / POST/api/sendCampaign.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_id |
integer | Yes | Campaign ID to send |
campaign_send_time |
string/integer | Optional | Unix timestamp or date string for scheduled send. Omit to send immediately |
format |
string | Optional | json or xml |
{
"success": "true",
"error": 200,
"error_msg": "OK",
"campaign_id": 88
}
Specific error codes:
111 — Scheduling failed (mail job creation error)112 — Campaign not ready (not in waiting to send state)113 — Campaign not found777 — No credits availableRetrieves details for a single campaign or lists all campaigns for the account.
GET / POST/api/currentCampaigns.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_id |
integer | Optional | Specific campaign ID. Omit to list campaigns |
load_all |
boolean | Optional | true to load all campaigns (paginated) |
start |
integer | Optional | Pagination offset |
length |
integer | Optional | Number of results per page |
format |
string | Optional | json or xml |
{
"success": "true",
"error": "200",
"error_msg": "OK",
"Campaign": {
"88": {
"is_template": "no",
"is_rsptemplate": "no",
"folder_id": 0,
"responder_id": 0,
"forward_id": 0,
"mailing_list": "5,12",
"selected_ids": ["5", "12"],
"type": "email",
"subject": "Monthly Newsletter - January 2025",
"content": "<html>...</html>",
"name": "January Newsletter",
"from_address": "news@acme.com",
"from_name": "Acme Corp",
"header": "",
"footer": "",
"theme_id": 0,
"twitter_text": "",
"facebook_text": "",
"notify": "no",
"response_sent": "no",
"finish": 0,
"failed": 12,
"success": 1488,
"total": 1500,
"create_dt": 1704067200,
"send_dt": 1704153600,
"status": "sent"
}
}
}
Campaign status values: waiting to send, scheduled, sending, sent, cancelled
Returns aggregate send/open/click statistics for a specific campaign.
GET / POST/api/campaignStatsSimple.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_id |
integer | Yes | Campaign ID |
format |
string | Optional | json or xml |
{
"CampaignStats": {
"total_sent": 1500,
"bounced": 12,
"opens": 850,
"unique_opens": 720,
"clicks": 310,
"unique_clicks": 275
}
}
Returns full time-series analytics for a campaign including opens, clicks, optouts, forwards, and replies broken down by date, hour, country, email client, and demographic.
GET / POST/api/campaignStatsDetailed.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_id |
integer | Yes | Campaign ID |
mailing_list |
integer | Optional | Filter stats to a specific mailing list |
format |
string | Optional | json or xml |
The XML response contains nested sections:
<CampaignStats id="{id}">
<Opens>
<Total>, <Unique>
<OpenByDate> — opens per calendar date with percentages
<OpenByHour> — opens per hour-of-day with percentages
<OpenEmailClient> — breakdowns by mail client (Gmail, Outlook, etc.)
<OpenCountry> — breakdowns by country
</Opens>
<Clicks>
<Total>, <Unique>
<ClickByDate>, <ClickByHour>
<ClickCountry>, <ClickByEmailClient>
<ClickDemographic>
</Clicks>
<Optouts> ... </Optouts>
<Forwards> ... </Forwards>
<Replies> ... </Replies>
</CampaignStats>
Retrieves email replies received in response to a campaign, filterable by campaign or contact email.
GET / POST/api/getReplies.phpformat parameter.| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
campaign_id |
integer | Conditional | Filter replies by campaign. Required if contact not provided |
contact |
string | Conditional | Filter replies by sender email address. Required if campaign_id not provided |
{
"success": "true",
"error": 200,
"error_msg": "OK",
"CampaignReplies": [
{
"id": 5,
"from": "customer@example.com",
"subject": "Re: Monthly Newsletter",
"content": "Hello, I'd like to...",
"date": "2024-01-16"
}
]
}
Returns the remaining sending credits for the account.
GET / POST/api/checkBalance.php| Parameter | Type | Required | Description |
|---|---|---|---|
api_key |
string | Yes | Account API key |
{
"status": "ok",
"prepaid": 15000,
"monthly": 5000,
"message": "ok"
}
{
"status": "failed",
"message": "invalid api key"
}