API

REST API for integrating with the MXGuard mail filtering system.

API Basics

Endpoint

https://my.mxguard.net/panelv32/api/?token=YOUR_API_TOKEN

Request Format

Requests are sent via POST with a JSON body. GET with URL parameters is also supported.

POST body (JSON)

{
    "request": "module_name",
    "action":  "action_name",
    "parameters": "values"
}

Authorization

The token is passed in the URL parameter token. You can generate a token in the control panel under "Access Tokens".

Supported Modules

request	Description
`tracker`	Email processing history
`message`	Details of a specific email
`queue`	Delivery queue
`domains`	List of domains
`domain`	Manage a single domain
`boxes`	List of mailboxes
`box`	Manage a single mailbox
`whitelists`	Whitelist
`blacklists`	Blacklist
`stats`	Statistics

Tracker

History of email message processing.

List of Emails

Request

{
    "request": "tracker",
    "action":  "list",
    "status":  "quarant",
    "date":    "day",
    "mail_to": "example.com"
}

Parameter	Description	Example
`status`	Email status	quarant, deliv, reject, error
`date`	Period	day, lastday, week, month
`subject`	Email subject	"Promotion"
`mail_from`	Sender	"sender@domain.com"
`mail_to`	Recipient	"user@example.com"
`smid`	Email ID	"2508200002183574501"
`ip_from`	Sender IP	"192.168.1.1"
`perpage`	Records per page	50
`page`	Page number	1

Response

{
    "perpage": "50",
    "page": 1,
    "records": 453,
    "pages": 10,
    "rows": {
        "1": {
            "byid":        {"key": "byid",    "val": "2508200002183574501"},
            "status":      {"key": "status",  "val": "zonde",
                            "view": "Spam traps"},
            "date":        {"key": "date",    "val": "today at 00:02, Wed"},
            "subject":     {"key": "subject", "val": "Contract Tender Notice"},
            "mail_from":   {"key": "mail_from","val": "srm@lukoil.com"},
            "mail_to":     {"key": "mail_to", "val": "yuri@mydomain.com"},
            "status_info": {"key": "status_info","val": "237"}
        }
    }
}

Detailed Email Information

Request

{
    "request": "message",
    "action":  "view",
    "byid":    "2508200324264421504"
}

Field	Description
`byid`	Unique email ID
`smid`	MXGuard Message ID
`date`	Date and time of processing
`helo`	Sender's EHLO greeting
`ip_from`	Sender's IP address
`mail_from`	Sender's email
`mail_to`	Recipient's email
`subject`	Email subject
`msize`	Email size
`quarantine`	Quarantine flag (0/1)
`status`	Processing status code
`status_text`	Text description of status
`head`	Email headers (raw)
`log`	Email processing log

Response (success)

{
    "records": 1,
    "code": "success",
    "rows": {
        "1": {
            "byid":        {"key":"byid","val":"2508200324264421504"},
            "smid":        {"key":"smid","val":"2508200324264421504"},
            "date":        {"key":"date","val":"August 20 at 03:24:26"},
            "ip_from":     {"key":"ip_from","val":"10.255.7.3"},
            "mail_from":   {"key":"mail_from","val":"sender@example.com"},
            "mail_to":     {"key":"mail_to","val":"sn@mydomain.com"},
            "subject":     {"key":"subject","val":"Sample email subject"},
            "msize":       {"key":"msize","val":"2.5 Kb"},
            "quarantine":  {"key":"quarantine","val":"0"},
            "status_text": {"key":"status_text",
                "val":"Email delivered to destination"},
            "head":        {"key":"head","val":"Email headers..."},
            "log":         {"key":"log","val":"Processing log..."}
        }
    }
}

Response (error)

{
    "records": 0,
    "code":   "failed",
    "error":  "notfound",
    "text":   "Record not found",
    "module": "tracker",
    "request": "view"
}

Email Queue

Queue list

{
    "request":  "queue",
    "action":   "list",
    "mail_from": "sn@example.com",
    "date":     "day",
    "perpage":  50,
    "page":     1
}

Force-send all

{
    "request": "queue",
    "action":  "sendall"
}

Frequent use of sendall may cause receiving servers to block you due to the burst of outgoing traffic.

Response (list)

{
    "records": 1, "code": "success",
    "rows": {
        "1": {
            "byid":      {"key":"byid","val":"2508221749084133220"},
            "status":    {"key":"status","val":"queue",
                          "view":"Queued"},
            "date":      {"key":"date","val":"today at 17:49, Fri"},
            "mail_from": {"key":"mail_from","val":"sn@example.com"},
            "mail_to":   {"key":"mail_to",
                "val":"recipient@example.com"},
            "status_info":{"key":"status_info","val":"340"}
        }
    },
    "actions": ["list", "sendall"],
    "module": "tracker", "request": "list"
}

Response (sendall)

{
    "code":       "success",
    "message":    "All queued emails have been sent",
    "sent_count": 15,
    "module":     "tracker",
    "request":    "sendall"
}

Domain Management

List of Domains

Request

{
    "request": "domains",
    "action":  "list",
    "active":  "1",
    "domain":  "example"
}

Response

{
    "records": 1, "code": "success",
    "rows": {
        "1": {
            "byid":      {"key":"byid","val":"mydomain.com"},
            "status":    {"key":"status","val":"normal",
                          "view":"Active"},
            "domain":    {"key":"domain","val":"mydomain.com"},
            "emailcnt":  {"key":"emailcnt","val":"31"},
            "mx_fail":   {"key":"mx_fail","val":"0"},
            "mxs_mx":    {"key":"mxs_mx",
                "val":"001:mx.mxguard.net;020:mx1.mxguard.net"},
            "spamlevel": {"key":"spamlevel","val":"6982 (90 %)"}
        }
    }
}

View Domain Settings

Request

{"request":"domain","action":"view","byid":"mydomain.com"}

Field	Description
`smtpserver`	Primary SMTP delivery server
`smtpserver2`	Backup SMTP server
`port`	SMTP server port
`databytes`	Email size limit
`num1`	Spam filtering level (1–10)
`boxtype`	Mailbox management type (add_safe / manual)
`masquarade`	Sender masquerading (yes/no)
`weblearn`	Web-based spam-filter training (enable/disable)
`dkim_selector`	DKIM selector
`dkim_pub`	DKIM public key

Adding a Domain

Request

{
    "request":    "domain",
    "action":     "add",
    "domain":     "newdomain.com",
    "smtpserver": "mx.yandex.ru",
    "boxtype":    "add_safe",
    "masquarade": "yes"
}

Parameter	Required
`domain`	Yes
`smtpserver`	Yes
`smtpserver2`	No
`port`	No
`boxtype`	No
`masquarade`	No
`comment`	No

Response (success)

{
    "code": "success",
    "rows": {"byid": 1855},
    "actions": ["view","save","add","delete","check"],
    "module": "domain", "request": "add"
}

Validation Error

{
    "code":  "failed",
    "error": "fields",
    "rows": {
        "smtpserver": {
            "errors": [{"error":"badhost",
                "error_text":"Host is invalid"}]
        }
    },
    "text": "Error filling in fields"
}

Editing a Domain

Request

{
    "request":    "domain",
    "action":     "save",
    "byid":       "mydomain.com",
    "smtpserver": "mx1.yandex.ru",
    "num1":       "7.00"
}

The response contains the changed fields along with their old and new values:

{"code":"success","rows":[{
    "field":"smtpserver","old":"mx.yandex.ru","val":"mx1.yandex.ru"
}]}

Deleting a Domain

Request

{
    "request": "domain",
    "action":  "delete",
    "byid":    "example.com"
}

All mailboxes on the domain must be deleted before the domain itself can be deleted. This operation cannot be undone.

Error Code	Description
`notfound`	Domain not found
`access_denied`	No permission to delete
`has_mailboxes`	Domain has mailboxes
`has_aliases`	Domain has aliases
`system_domain`	System domain

Mailbox Management

List of Mailboxes

{
    "request": "boxes",
    "action":  "list",
    "domain":  "mydomain.com",
    "status":  "active",
    "email":   "admin@",
    "perpage": 100,
    "page":    1
}

View Mailbox

{
    "request": "box",
    "action":  "view",
    "byid":    "user@mydomain.com"
}

Adding a Mailbox

{
    "request":  "box",
    "action":   "add",
    "email":    "newuser@mydomain.com",
    "password": "securepassword123"
}

Editing a Mailbox

{
    "request":  "box",
    "action":   "save",
    "byid":     "user@mydomain.com",
    "comment":  "Administrator",
    "password": "newpassword456"
}

Deleting a Mailbox

{
    "request": "box",
    "action":  "delete",
    "byid":    "user@mydomain.com"
}

Response Field	Description
`byid`	Mailbox email (ID)
`status`	active / disabled / zonde
`email`	Full email address
`emailcnt`	Number of emails
`boxunused`	Unused flag
`boxnospam`	Disable filtering
`comment`	Comment
`spamlevel`	Spam level

Error Code	Description
`notfound`	Mailbox not found
`already_exists`	Mailbox already exists
`invalid_email`	Invalid email format
`domain_not_exists`	Domain does not exist
`password_too_weak`	Password is too weak
`quota_exceeded`	Mailbox quota exceeded

Whitelist

List Entries

{
    "request":    "whitelists",
    "action":     "list",
    "status":     "personal",
    "address":    "gmail.com",
    "to_address": "user@mydomain.com"
}

Adding an Entry

{
    "request":    "whitelists",
    "action":     "add",
    "address":    "partner@company.com",
    "to_address": "user@mydomain.com",
    "status":     "personal",
    "comment":    "Trusted partner"
}

Editing / Deleting

{
    "request": "whitelists",
    "action":  "save",
    "byid":    "61539",
    "comment": "Updated comment"
}

{"request":"whitelists","action":"delete","byid":"61539"}

Sample List Response

{
    "records": 483, "code": "success",
    "rows": {
        "1": {
            "byid":       {"key":"byid","val":"61539"},
            "status":     {"key":"status","val":"personal",
                           "view":"Personal"},
            "address":    {"key":"address",
                "val":"partner@gmail.com"},
            "to_address": {"key":"to_address",
                "val":"eg@mydomain.com"},
            "comment":    {"key":"comment",
                "val":"Partner LLC"}
        }
    }
}

Entries with to_address: "(for all)" apply to every recipient on the domain. Whitelisting an entire domain (gmail.com) can significantly reduce the filtering level.

Blacklist

List Entries

{
    "request": "blacklists",
    "action":  "list",
    "status":  "domain",
    "address": "*.com"
}

Adding an Entry

{
    "request":    "blacklists",
    "action":     "add",
    "address":    "*.spammer.com",
    "to_address": "(for all)",
    "status":     "domain",
    "comment":    "Known spammer"
}

Editing / Deleting

{"request":"blacklists","action":"save",
 "byid":"192605","comment":"Updated"}

{"request":"blacklists","action":"delete","byid":"192605"}

Type	Example address
Email	`spammer@example.com`
Domain	`*.example.com`
IP	`192.168.1.1`
IP range	`192.168.1.*`

status	Description
`personal`	Personal entry
`domain`	Entire domain
`ip`	By IP address

Statistics

Retrieving Statistics

{
    "request":   "stats",
    "action":    "list",
    "period":    "month",
    "domain":    "example.com"
}

Detailed Statistics

{
    "request": "stats",
    "action":  "view",
    "byid":    "2024-08",
    "domain":  "example.com"
}

Parameter	Description
`period`	day, week, month, year
`domain`	Filter by domain
`date_from`	Period start (YYYY-MM-DD)
`date_to`	Period end (YYYY-MM-DD)

Error Codes

HTTP	Status	Description
200	Success	Request completed successfully
400	Bad Request	Invalid request syntax
401	Unauthorized	Invalid or missing token
403	Forbidden	Access denied
404	Not Found	Object not found
500	Internal Error	Internal server error

error	Description
`notfound`	Record not found
`access_denied`	No access
`denied`	No permission for this operation
`fields`	Field validation errors
`required`	Required field not filled in
`badhost`	Invalid host format
`invalid_email`	Invalid email format
`invalid_domain`	Invalid domain format
`invalid_address`	Invalid address format
`invalid_ip`	Invalid IP format
`already_exists`	Record already exists
`domain_exists`	Domain already exists
`has_mailboxes`	Domain contains mailboxes
`quota_exceeded`	Quota exceeded
`password_too_weak`	Password is too weak
`queue_empty`	Queue is empty
`database_error`	Database error

Example Requests

GET Request with URL Parameters

cURL

curl -X GET \
  'https://my.mxguard.net/panelv32/api/?token=YOUR_TOKEN&request=tracker&action=list&mail_from=newsletter@company.com&date=week&status=quarant' \
  -H 'Content-Type: application/json'

POST Request with JSON Body

cURL

curl -X POST \
  'https://my.mxguard.net/panelv32/api/?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": "tracker",
    "action":  "list",
    "mail_from": "billing@service.com",
    "date":    "month",
    "status":  "deliv",
    "subject": "Invoice",
    "perpage": 100,
    "page":    1
}'

Python

import requests, json

TOKEN = "YOUR_API_TOKEN"
URL   = f"https://my.mxguard.net/panelv32/api/?token={TOKEN}"

def api(payload):
    r = requests.post(URL, json=payload,
                      headers={"Content-Type": "application/json"})
    return r.json()

# List of quarantined emails
print(api({"request":"tracker","action":"list","status":"quarant","date":"day"}))

# Add a domain
print(api({"request":"domain","action":"add",
           "domain":"example.com","smtpserver":"mail.example.com"}))

# Working with the queue
queue = api({"request":"queue","action":"list","perpage":100})
if queue.get("records", 0) > 0:
    api({"request":"queue","action":"sendall"})

API v4 is the current version of the control panel. It maintains compatibility with the v3 request format, but returns simplified JSON without the intermediate {"key":…,"val":…} wrapper, supports Bearer authorization, and extends the set of modules.

API v4 Basics

Endpoint

https://my.mxguard.net/panel/api/

Authorization

Two methods are supported — the old one (token in the URL, for backward compatibility) and the new one (Bearer header):

Option 1 — token in the URL (v3-compatible)

POST https://my.mxguard.net/panel/api/?token=YOUR_TOKEN

Option 2 — Bearer header (recommended)

POST https://my.mxguard.net/panel/api/
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request Format

Same JSON format as in v3. application/x-www-form-urlencoded is also accepted.

{
    "request": "module",
    "action":  "action_name",
    "parameters": "values"
}

Response Format — What Changed

In v3, every data field is wrapped in an object {"key":"…","val":"…"}. In v4, data is returned directly:

v3 — nested format

{
    "rows": {
        "1": {
            "byid":   {"key":"byid","val":"123"},
            "domain": {"key":"domain","val":"example.com"},
            "status": {"key":"status","val":"normal",
                       "view":"Active"}
        }
    }
}

v4 — flat format

{
    "code": "success",
    "records": 1,
    "page":    1,
    "pages":   1,
    "perpage": 50,
    "rows": [
        {
            "byid":   "123",
            "domain": "example.com",
            "status": "normal"
        }
    ]
}

The view field (human-readable status name) is moved to a separate field with the _label suffix where needed — for example, "status_label": "Active".

Pagination

All list methods support the page and perpage parameters (default 50, maximum 500). The response includes: records (total records), pages (total pages), page (current page).

Tracker v4

Requests are identical to v3; the response uses the flat format.

Request

{
    "request": "tracker",
    "action":  "list",
    "status":  "quarant",
    "date":    "day",
    "mail_to": "example.com",
    "perpage": 50,
    "page":    1
}

Response

{
    "code":    "success",
    "records": 453,
    "page":    1, "pages": 10, "perpage": 50,
    "rows": [
        {
            "byid":      "2508200002183574501",
            "status":    "zonde",
            "date":      "2025-08-20 00:02:00",
            "subject":   "Contract Tender Notice",
            "mail_from": "srm@lukoil.com",
            "mail_to":   "yuri@mydomain.com"
        }
    ]
}

Email Details

Request

{
    "request": "message",
    "action":  "view",
    "byid":    "2508200324264421504"
}

Response

{
    "code": "success", "records": 1,
    "rows": [{
        "byid":        "2508200324264421504",
        "date":        "2025-08-20T03:24:26Z",
        "ip_from":     "10.255.7.3",
        "mail_from":   "sender@example.com",
        "mail_to":     "sn@mydomain.com",
        "subject":     "Sample email subject",
        "msize_bytes": 2560,
        "quarantine":  false,
        "status":      "5",
        "status_text": "Email delivered",
        "head":        "…raw headers…",
        "log":         "…processing log…"
    }]
}

Domains v4

List Domains

{
    "request": "domains",
    "action":  "list",
    "active":  1
}

View Domain

{
    "request": "domain",
    "action":  "view",
    "byid":    "example.com"
}

Add

{
    "request":    "domain",
    "action":     "add",
    "domain":     "newdomain.com",
    "smtpserver": "mx.yandex.ru"
}

Edit

{
    "request":    "domain",
    "action":     "save",
    "byid":       "example.com",
    "smtpserver": "mx1.yandex.ru",
    "num1":       7.0
}

Delete

{
    "request": "domain",
    "action":  "delete",
    "byid":    "example.com"
}

Response (list)

{
    "code": "success", "records": 2,
    "rows": [
        {
            "byid":      "example.com",
            "status":    "normal",
            "domain":    "example.com",
            "emailcnt":  31,
            "mx_fail":   0,
            "mxs_mx":    "mx.mxguard.net",
            "spam_pct":  90
        }
    ]
}

Response (add)

{
    "code": "success",
    "byid": 1855,
    "module": "domain",
    "request": "add"
}

Response (save)

{
    "code": "success",
    "changed": [
        {"field":"smtpserver",
         "old":"mx.yandex.ru",
         "val":"mx1.yandex.ru"}
    ]
}

Mailboxes v4

Requests are identical to v3. New fields in the responses:

New Field	Description
`created_at`	Mailbox creation date (ISO 8601)
`last_mail_at`	Date of the last email
`spam_cnt_7d`	Spam count over 7 days
`deliv_cnt_7d`	Delivered count over 7 days

Whitelist and Blacklist v4

Requests are identical to v3. In the response, the address_type field explicitly indicates the type: email, domain, ip — instead of inferring the type from the string format.

Sample blacklists/list Response (v4)

{
    "code": "success", "records": 95,
    "rows": [
        {
            "byid":         "192605",
            "status":       "domain",
            "address":      "*.askona.ru",
            "address_type": "domain",
            "to_address":   null,
            "comment":      "Askona"
        }
    ]
}

Processing Rules (new in v4)

The rules module is new in v4 and manages filtering rules.

List Rules

{
    "request": "rules",
    "action":  "list",
    "domain":  "example.com"
}

Create Rule

{
    "request":  "rule",
    "action":   "add",
    "username": "example.com",
    "rl_name":  "Block newsletter",
    "rl_logic": "and",
    "rl_stop":  1,
    "criteria": [
        {"rc_type":"from",
         "rc_match":"wildcard",
         "rc_value":"*@newsletter.com",
         "rc_negate": false}
    ],
    "actions": [
        {"ra_type":"discard","ra_params":"{}"}
    ]
}

Response (list)

{
    "code": "success", "records": 3,
    "rows": [
        {
            "byid":     "42",
            "rl_name":  "Block newsletter",
            "rl_logic": "and",
            "rl_stop":  true,
            "active":   true,
            "criteria_cnt": 1,
            "actions_cnt":  1
        }
    ]
}

Response (add)

{
    "code":   "success",
    "byid":   42,
    "module": "rule",
    "request":"add"
}

rc_type	Condition
`from`	Sender (From)
`rcpt`	Recipient (To)
`ip`	Sender IP
`subject`	Email subject
`keyword`	Keyword in body
`header`	Email header

ra_type	Action	ra_params
`spam`	Mark as spam	`{"score": 10}`
`discard`	Discard silently	`{}`
`reject`	Reject with code 550	`{"message": "Blocked"}`
`forward_email`	Forward to email	`{"email": "copy@example.com"}`
`forward_server`	Forward to SMTP server	`{"host": "mx.other.ru", "port": 25}`
`tag_subject`	Add prefix to subject	`{"prefix": "[SPAM]"}`
`add_header`	Add header	`{"name": "X-Tag", "value": "promo"}`

Errors v4

The error format is unified:

{
    "code":    "failed",
    "error":   "notfound",
    "text":    "Domain not found",
    "module":  "domain",
    "request": "view",
    "fields": {
        "smtpserver": [
            {"error": "badhost", "text": "Host is invalid"}
        ]
    }
}

The fields field appears only for the fields error and contains details for each field. Error codes are the same as in v3, plus new ones:

Code (new in v4)	Description
`rule_not_found`	Rule not found
`criterion_not_found`	Rule criterion not found
`action_not_found`	Rule action not found
`invalid_token`	Token is invalid or revoked
`rate_limited`	Request rate limit exceeded

Example Requests v4

cURL with Bearer Token

curl -X POST https://my.mxguard.net/panel/api/ \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"request":"tracker","action":"list","status":"quarant","date":"day"}'

Python

import requests

TOKEN = "YOUR_API_TOKEN"
BASE  = "https://my.mxguard.net/panel/api/"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
})

def api(payload):
    r = session.post(BASE, json=payload)
    r.raise_for_status()
    return r.json()

# List domains
domains = api({"request":"domains","action":"list"})
for row in domains.get("rows", []):
    print(row["domain"], row["emailcnt"])

# Create a rule
rule = api({
    "request":  "rule",
    "action":   "add",
    "username": "example.com",
    "rl_name":  "Block newsletter",
    "rl_logic": "and",
    "criteria": [{"rc_type":"from","rc_match":"wildcard",
                  "rc_value":"*@promo.com"}],
    "actions":  [{"ra_type":"discard","ra_params":"{}"}]
})
print("Rule created:", rule.get("byid"))