API Documentation

Base URL

https://api.adsmedia.live/v1

📑 Quick Navigation

Authentication
Send Email
Campaigns
Lists & Contacts
Schedules (Tasks)
Servers
Domain Verification
Statistics
Events
Suppression Check
Account

🔐

Authentication

All API requests require authentication using your API key. You can authenticate using one of these methods:

Authentication Methods

Option 1: Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY

Option 2: X-API-Key Header

X-API-Key: YOUR_API_KEY

Option 3: Query Parameter

?key=YOUR_API_KEY

GET /v1/ping

Test API connectivity and authentication.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.adsmedia.live/v1/ping"

Response:

{
  "success": true,
  "data": {
    "message": "API is working!",
    "userId": "123",
    "method": "GET",
    "version": "1.0.0"
  },
  "timestamp": "2025-12-01T18:00:00+02:00"
}

🚀

Send Email

Send emails directly via API. Two modes available:

Single send — Synchronous, for transactional emails (no tracking/statistics)
Batch send — Asynchronous, for marketing emails (full tracking, personalization, statistics)

POST /v1/send

Send a single transactional email synchronously. Note: No open/click tracking or statistics. Use for password resets, order confirmations, notifications, etc.

Request Body (JSON)

Parameter	Type	Description
`to`	string	Required Recipient email address
`to_name`	string	Optional Recipient name
`subject`	string	Required Email subject line
`html`	string	Required HTML content (required unless text-only)
`text`	string	Auto/Required Plain text version. Auto-generated from HTML if not provided
`type`	integer	Optional 1=HTML+text (default), 2=HTML only, 3=text only
`from_name`	string	Optional Sender display name (default: ADSMedia)
`reply_to`	string	Optional Reply-to email address
`server_id`	integer	Optional Specific server ID (random available if not specified)
`unsubscribe_url`	string	Optional URL for List-Unsubscribe header

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "[email protected]", "to_name": "John Doe", "subject": "Welcome to our service!", "html": "<h1>Hello John!</h1><p>Welcome aboard.</p>", "from_name": "Support Team" }' \ "https://api.adsmedia.live/v1/send"

Response

{
  "success": true,
  "data": {
    "message_id": "api-1701432000-a1b2c3d4e5f6g7h8",
    "send_id": 12345,
    "to": "[email protected]",
    "from": "[email protected]",
    "server": "yourdomain.com",
    "status": "sent"
  }
}

POST /v1/send/batch

Send up to 1000 marketing emails in a batch. Creates a task that processes asynchronously with full tracking (opens, clicks, unsubscribes).

Request Body (JSON)

Parameter	Type	Description
`recipients`	array	Required Array of recipients (max 1000)
`recipients[].email`	string	Required Recipient email
`recipients[].name`	string	Optional Recipient name (for %%First Name%% personalization)
`subject`	string	Required Email subject line
`html`	string	Required HTML content (auto-wrapped if no <body> tag)
`text`	string	Optional Plain text version (auto-generated from HTML if not provided)
`preheader`	string	Optional Email preheader (preview text)
`from_name`	string	Optional Sender display name
`server_id`	integer	Optional Specific server ID (random if not specified)

Personalization Placeholders

Use these placeholders in subject and HTML — they will be replaced per recipient:

Placeholder	Type	Description
`%%First Name%%`	string	Recipient's first name (from recipients[].name)
`%%Last Name%%`	string	Recipient's last name
`%%emailaddress%%`	string	Recipient's email address
`%%Sender Name%%`	string	Your sender name (from_name)
`%%unsubscribelink%%`	URL	Unsubscribe link (auto-added if missing)
`%%webversion%%`	URL	View in browser link

💡 Auto-formatting

Simple HTML without <body> tag is automatically wrapped in a proper HTML structure. If no %%unsubscribelink%% is provided, an unsubscribe footer is automatically added for compliance.

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipients": [ {"email": "[email protected]", "name": "John"}, {"email": "[email protected]", "name": "Jane"}, {"email": "[email protected]"} ], "subject": "Special Offer for %%First Name%%!", "html": "<h1>Hello %%First Name%%!</h1><p>Check out our deals.</p>", "from_name": "Marketing Team" }' \ "https://api.adsmedia.live/v1/send/batch"

Response

{
  "success": true,
  "data": {
    "task_id": 789,
    "campaign_id": 456,
    "list_id": 123,
    "recipients_count": 3,
    "status": "prep",
    "message": "Batch task created. Sending will start within 1 minute."
  }
}

📊 Statistics

Use the returned task_id with /v1/stats/campaign?id={task_id} to get opens, clicks, bounces, and other statistics after sending completes.

GET /v1/send/status?message_id={id}

Get the status of a sent email by message ID or send ID.

Parameter	Type	Description
`message_id`	string	Optional* Message ID returned from /send
`id`	integer	Optional* Send ID returned from /send

* Either message_id or id is required

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.adsmedia.live/v1/send/status?message_id=api-1701432000-a1b2c3d4"

📧

Campaigns

Campaigns are email templates containing HTML content, subject lines, and preheaders.

GET /v1/campaigns

List all campaigns.

Parameter	Type	Description
`limit`	integer	Optional Max results (default: 50)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.adsmedia.live/v1/campaigns"

GET /v1/campaigns/get?id={id}

Get a specific campaign by ID.

Parameter	Type	Description
`id`	integer	Required Campaign ID

POST /v1/campaigns/create

Create a new campaign.

Request Body (JSON)

Parameter	Type	Description
`name`	string	Required Campaign name
`subject`	string	Required Email subject line
`type`	integer	Optional 1=HTML+text (default), 2=HTML only, 3=text only
`html`	string	Required HTML content (required for type 1 and 2)
`text`	string	Auto/Required Plain text version. Auto-generated from HTML for type 1/2. Required for type 3
`preheader`	string	Optional Preheader text

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Email",
    "subject": "Welcome to our service!",
    "preheader": "Thanks for signing up",
    "html": "<h1>Hello %%First Name%%!</h1><p>Welcome aboard.</p>"
  }' \
  "https://api.adsmedia.live/v1/campaigns/create"

Response

{
  "success": true,
  "data": {
    "id": 78,
    "name": "Welcome Email",
    "created": "2025-12-02 10:30:00"
  }
}

PUT /v1/campaigns/update?id={id}

Update an existing campaign. Only provided fields will be updated.

Request Body (JSON)

Parameter	Type	Description
`name`	string	Optional Campaign name
`subject`	string	Optional Email subject line
`type`	integer	Optional 1=HTML+text, 2=HTML only, 3=text only
`html`	string	Optional HTML content
`text`	string	Optional Plain text version
`preheader`	string	Optional Preheader text

Example Request

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Updated Subject Line"}' \
  "https://api.adsmedia.live/v1/campaigns/update?id=45"

DELETE /v1/campaigns/delete?id={id}

Delete a campaign (soft delete).

📋

Lists & Contacts

GET /v1/lists

List all subscriber lists with hierarchical structure. Child lists are nested inside their parent's children array.

Response

{
  "success": true,
  "data": {
    "lists": [
      {
        "id": 123,
        "name": "Newsletter Subscribers",
        "count": 15000,
        "type": 1,
        "children": [
          {
            "id": 456,
            "name": "Segment A - Active",
            "count": 8500,
            "type": 1
          },
          {
            "id": 457,
            "name": "Segment B - Inactive",
            "count": 6500,
            "type": 1
          }
        ]
      },
      {
        "id": 124,
        "name": "Product Updates",
        "count": 5200,
        "type": 1
      }
    ]
  }
}

Note: children array is only included if the list has child lists.

GET /v1/lists/get?id={id}

Get detailed information about a specific list, including sample contacts and child lists if any.

Parameter	Type	Description
`id`	integer	Required List ID

Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Newsletter Subscribers",
    "count": 15000,
    "type": 1,
    "children": [
      {"id": 456, "name": "Segment A", "count": 8500, "type": 1}
    ],
    "sample_contacts": [
      {"email": "[email protected]", "fields": {"name": "John"}}
    ]
  }
}

Note: children array is only included if the list has child lists. sample_contacts returns up to 10 contacts.

POST /v1/lists/create

Create a new list.

Request Body (JSON)

Parameter	Type	Description
`name`	string	Required List name
`type`	integer	Optional 1=email (default), 3=phone

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter Subscribers"}' \
  "https://api.adsmedia.live/v1/lists/create"

Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Newsletter Subscribers",
    "type": 1
  }
}

GET /v1/lists/contacts?id={id}

Get contacts from a list.

Parameter	Type	Description
`id`	integer	Required List ID
`limit`	integer	Optional Max results (default: 100, max: 1000)
`offset`	integer	Optional Pagination offset

POST /v1/lists/contacts/add?id={id}

Add contacts to a list (max 1000 per request).

Request Body (JSON)

Parameter	Type	Description
`contacts`	array	Required Array of contact objects
`contacts[].email`	string	Required Email address
`contacts[].firstName`	string	Optional First name
`contacts[].lastName`	string	Optional Last name
`contacts[].custom1`	string	Optional Custom field 1
`contacts[].custom2`	string	Optional Custom field 2

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contacts": [ {"email": "[email protected]", "firstName": "John", "lastName": "Doe"}, {"email": "[email protected]", "firstName": "Jane"} ] }' \ "https://api.adsmedia.live/v1/lists/contacts/add?id=45"

Response

{
  "success": true,
  "data": {
    "added": 2,
    "duplicates": 0,
    "list_id": 45
  }
}

DELETE /v1/lists/contacts/delete?id={id}

Remove contacts from a list.

Request Body (JSON)

Parameter	Type	Description
`emails`	array	Required Array of email addresses to remove

Example Request

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"emails": ["[email protected]", "[email protected]"]}' \ "https://api.adsmedia.live/v1/lists/contacts/delete?id=45"

Response

{
  "success": true,
  "data": {
    "deleted": 2,
    "list_id": 45
  }
}

POST /v1/lists/split?id={id}

Split a large list into smaller segments. Required for lists over 150,000 contacts before sending.

Request Body (JSON)

Parameter	Type	Description
`count`	integer	Optional Number of splits. If not provided, auto-calculated based on 35k per split.

💡 Split Size Limits

Minimum: 15,000 contacts per split
Maximum: 35,000 contacts per split

If count is omitted, the system auto-calculates optimal splits (~35k each). If your count results in splits outside these limits, you'll get an error with the valid range.

Example Request (auto)

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.adsmedia.live/v1/lists/split?id=123"

Response

{
  "success": true,
  "data": {
    "list_id": 123,
    "list_name": "Newsletter Subscribers",
    "original_count": 105000,
    "splits": [
      {"id": 456, "name": "Newsletter Subscribers (split 1)", "count": 35000},
      {"id": 457, "name": "Newsletter Subscribers (split 2)", "count": 35000},
      {"id": 458, "name": "Newsletter Subscribers (split 3)", "count": 35000}
    ],
    "message": "List split into 3 parts"
  }
}

Note: Split lists appear as children in the parent list. Send to individual splits, not the parent. Re-splitting a list deletes existing splits first.

📅

Schedules (Sending Tasks)

Schedules are sending tasks that combine a campaign, list, and server to execute email delivery.

GET /v1/schedules

List all schedules/tasks.

Parameter	Type	Description
`status`	string	Optional Filter by status (queue, prep, sending, done, paused)

POST /v1/schedules/create

Create a new sending task.

Request Body (JSON)

Parameter	Type	Description
`campaign_id`	integer	Required Campaign ID
`list_id`	integer	Required List ID
`server_id`	integer	Required Server ID
`sender_name`	string	Optional Sender display name
`schedule`	string	Optional Schedule datetime (YYYY-MM-DD HH:MM:SS)

⚠️ List Restrictions

Parent lists with splits: Cannot send to a list that has child lists (splits). Use individual split lists instead.
Maximum 150,000 contacts: Lists larger than 150k contacts must be split before sending.

Example Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": 45,
    "list_id": 123,
    "server_id": 1,
    "sender_name": "John from Company",
    "schedule": "2025-12-15 10:00:00"
  }' \
  "https://api.adsmedia.live/v1/schedules/create"

Response

{
  "success": true,
  "data": {
    "id": 456,
    "status": "scheduled",
    "schedule": "2025-12-15 10:00:00"
  }
}

PUT /v1/schedules/update?id={id}

Update schedule sender name or datetime. Cannot edit if status is sending or done.

Request Body (JSON)

Parameter	Type	Description
`sender_name`	string	Optional New sender display name
`schedule`	string	Optional New datetime (YYYY-MM-DD HH:MM:SS)

Example Request

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender_name": "New Name", "schedule": "2025-12-20 14:00:00"}' \
  "https://api.adsmedia.live/v1/schedules/update?id=456"

Response

{
  "success": true,
  "data": {
    "id": 456,
    "updated": {
      "sender_name": "New Name",
      "schedule": "2025-12-20 14:00:00"
    },
    "message": "Schedule updated successfully"
  }
}

POST /v1/schedules/pause?id={id}

Pause an active schedule.

POST /v1/schedules/resume?id={id}

Resume a paused schedule.

DELETE /v1/schedules/stop?id={id}

Stop and delete a schedule permanently.

🖥️

Servers

GET /v1/servers

List all sending servers with status, limits, and warmup progress.

Response includes:

Server status and IP address
Daily sending limit and sent count
Warmup status and progress
Blacklist status
Health score

GET /v1/servers/get?id={id}

Get detailed information about a specific server.

🌐

Domain Verification

GET /v1/domains/verify?server_id={id}

Comprehensive DNS verification for a server's domain. Checks SPF, DKIM, DMARC, MX, PTR, DNSSEC (DS), and TLSA (DANE) with certificate validation.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.adsmedia.live/v1/domains/verify?server_id=15"

Response:

{
  "domain": "example.com",
  "ip": "203.0.113.10",
  "checks": {
    "spf": { "status": "pass", "record": "v=spf1 ip4:203.0.113.10 -all" },
    "dkim": { "status": "pass", "selector": "default" },
    "dmarc": { "status": "pass" },
    "mx": { "status": "pass" },
    "ptr": { "status": "pass" },
    "dnssec": { "status": "pass", "ds_records": [...] },
    "tlsa": { "status": "valid", "valid": 3 }
  },
  "overall": "pass",
  "score": { "base": 100, "dnssec": 5, "tlsa": 5, "total": 110 }
}

📊

Statistics

GET /v1/stats/overview

Get overall sending statistics across all campaigns.

GET /v1/stats/campaign?id={id}

Get statistics for a specific campaign/task.

GET /v1/stats/hourly?id={id}

Get hourly breakdown of opens/clicks for a task.

GET /v1/stats/daily?id={id}

Get daily breakdown of opens/clicks for a task.

GET /v1/stats/countries?id={id}

Get geographic distribution of opens/clicks.

GET /v1/stats/bounces?id={id}

Get bounce details grouped by reason.

GET /v1/stats/providers?id={id}

Get statistics by email provider (Gmail, Outlook, etc.).

⚡

Events

GET /v1/stats/events?id={id}

Get detailed events (opens, clicks, bounces, unsubscribes) for a task.

Parameter	Type	Description
`id`	integer	Required Task/Schedule ID
`type`	string	Optional Filter: open, click, bounce, unsubscribe, sent
`email`	string	Optional Filter by specific email
`limit`	integer	Optional Max results (default: 100, max: 1000)
`offset`	integer	Optional Pagination offset

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.adsmedia.live/v1/stats/events?id=123&type=open&limit=50"

🚫

Suppression Check

GET /v1/suppressions/check?email={email}

Check if a specific email is suppressed (bounced, unsubscribed, or blocked).

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.adsmedia.live/v1/suppressions/[email protected]"

Response:

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "suppressed": true,
    "reason": "hard bounce"
  }
}

👤

Account

GET /v1/account

Get account information.

GET /v1/account/usage

Get usage statistics and limits.

Response includes:

Server count and daily limits
Lists and subscriber counts
Active schedules
This month's sending stats

GET /v1/account/api-keys

Get your current API key.

POST /v1/account/api-keys/regenerate

Generate a new API key. Warning: This invalidates your current key immediately.

⏱️

Rate Limiting

API requests are rate-limited to ensure fair usage:

100 requests per minute per API key
Rate limit headers are included in responses
Exceeding the limit returns HTTP 429 (Too Many Requests)

⚠️

Error Handling

All errors return a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Campaign not found"
  },
  "timestamp": "2025-12-01T18:00:00+02:00"
}

HTTP Code	Error Code	Description
400	missing_*	Required parameter missing
401	unauthorized	Invalid or missing API key
404	not_found	Resource not found
405	method_not_allowed	Wrong HTTP method
429	rate_limit	Too many requests
500	internal_error	Server error

API Documentation

Base URL

📑 Quick Navigation

Authentication

Authentication Methods

Example Request

Response:

Send Email

Request Body (JSON)

Example Request

Response

Request Body (JSON)

Personalization Placeholders

💡 Auto-formatting

Example Request

Response

📊 Statistics

Example Request

Campaigns

Example Request

Request Body (JSON)

Example Request

Response

Request Body (JSON)

Example Request

Lists & Contacts

Response

Response

Request Body (JSON)

Example Request

Response

Request Body (JSON)

Example Request

Response

Request Body (JSON)

Example Request

Response

Request Body (JSON)

💡 Split Size Limits

Example Request (auto)

Response

Schedules (Sending Tasks)

Request Body (JSON)

⚠️ List Restrictions

Example Request

Response

Request Body (JSON)

Example Request

Response

Servers

Response includes:

Domain Verification

Example Request

Response:

Statistics

Events

Example Request

Suppression Check

Example Request

Response:

Account

Response includes:

Rate Limiting

Error Handling

Welcome Back