mx2api API
Every endpoint returns JSON. Authenticate with the API key from your
Profile page using Authorization: Bearer mx2_....
API keys are created and revoked in the Profile page — there is no API endpoint for managing them.
Base URL & authentication
| Base URL | https://mx2api.com/api/v1 |
|---|---|
| Auth header | Authorization: Bearer mx2_xxxxxxxx |
| Content type | application/json; charset=utf-8 (always JSON, including errors) |
| Query options | ?pretty=1 for indented output, ?include=text to embed message bodies in the list |
GET /api/v1/me
Returns the authenticated user and how the request was authenticated.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/me"
Response
{
"user": {
"id": 1,
"email": "[email protected]",
"created_at": "2026-11-16 10:00:00"
},
"auth": "api_key"
}
GET /api/v1/messages
Inbox listing. Parameters: domain, to, limit (max 200), offset, include.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/messages?domain=yourdomain.com&limit=50"
Response
{
"total": 2,
"limit": 50,
"offset": 0,
"messages": [
{
"id": 42,
"message_id": "<[email protected]>",
"domain": "yourdomain.com",
"to": "[email protected]",
"from": "[email protected]",
"from_name": "Sender",
"subject": "Your verification code",
"size": 1842,
"attachments": 1,
"read": false,
"received_at": "2026-11-16 10:38:35"
},
{
"id": 41,
"message_id": "<[email protected]>",
"domain": "yourdomain.com",
"to": "[email protected]",
"from": "[email protected]",
"from_name": null,
"subject": "Weekly digest",
"size": 53120,
"attachments": 0,
"read": true,
"received_at": "2026-11-16 09:12:04"
}
]
}
GET /api/v1/messages?domain=yourdomain.com
Empty inbox — no message has arrived yet.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/messages"
Response
{
"total": 0,
"limit": 50,
"offset": 0,
"messages": []
}
GET /api/v1/messages/:id
Full message: headers, text, html and attachments.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/messages/42"
Response
{
"id": 42,
"message_id": "<[email protected]>",
"domain": "yourdomain.com",
"to": "[email protected]",
"from": "[email protected]",
"from_name": "Sender",
"reply_to": "[email protected]",
"subject": "Your verification code",
"text": "Hello,\n\nYour code is 482913.\n",
"html": "<p>Hello,</p><p>Your code is <b>482913</b>.</p>",
"headers": {
"content-type": "text/plain; charset=utf-8",
"from": "Sender <[email protected]>"
},
"size": 1842,
"read": true,
"received_at": "2026-11-16 10:38:35",
"attachments": [
{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size": 20480,
"url": "/api/v1/messages/42/attachments/invoice.pdf"
}
]
}
GET /api/v1/messages/:id
Message without any content (empty body).
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/messages/43"
Response
{
"id": 43,
"message_id": "<[email protected]>",
"domain": "yourdomain.com",
"to": "[email protected]",
"from": "[email protected]",
"from_name": null,
"reply_to": null,
"subject": "",
"text": "",
"html": "",
"headers": {},
"size": 0,
"read": false,
"received_at": "2026-11-16 10:40:02",
"attachments": []
}
GET /api/v1/messages/:id/raw
Original message source (.eml) — binary download, not JSON.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ -o message.eml \ "https://mx2api.com/api/v1/messages/42/raw"
Response
HTTP/1.1 200 OK Content-Type: message/rfc822 Content-Disposition: attachment; filename="message-42.eml" From: Sender <[email protected]> To: [email protected] Subject: Your verification code Message-ID: <[email protected]> Date: Sun, 16 Nov 2026 10:38:35 +0000 Hello, Your code is 482913.
GET /api/v1/messages/:id/attachments/:filename
Downloads a single attachment — binary download, not JSON.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ -o invoice.pdf \ "https://mx2api.com/api/v1/messages/42/attachments/invoice.pdf"
Response
HTTP/1.1 200 OK Content-Type: application/pdf Content-Disposition: attachment; filename="invoice.pdf" %PDF-1.7 ... (binary content of the attachment)
POST /api/v1/messages/:id/read
Marks a message as read.
Request
curl -X POST -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/messages/42/read"
Response
{
"ok": true
}
DELETE /api/v1/messages/:id
Deletes a message permanently.
Request
curl -X DELETE -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/messages/42"
Response
{
"ok": true
}
GET /api/v1/domains
All domains connected to your account. Every domain carries its plan and usage: messages received in the current month, the monthly limit and the total number of received messages.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/domains"
Response
{
"domains": [
{
"id": 1,
"user_id": 1,
"domain": "yourdomain.com",
"verify_token": "",
"mx_host": "mx.mx2api.com",
"mx_checked_at": "2026-11-16T10:38:35.000Z",
"mx_attempts": 3,
"status": "active",
"created_at": "2026-11-16 09:00:00",
"usage": {
"plan": "free",
"limit": 100,
"used": 12,
"remaining": 88,
"total": 340,
"unlimited": false,
"upgrade_price": 500,
"upgrade_currency": "USD",
"upgrade_price_display": "$5.00",
"quota_reached": false
}
}
]
}
POST /api/v1/domains/:domain/upgrade
Upgrades a domain to the unlimited plan - unlimited messages per month, $5.00 per month. Free domains accept 100 messages per month.
Request
curl -X POST -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/domains/yourdomain.com/upgrade"
Response
{
"domain": "yourdomain.com",
"plan": "unlimited",
"order_id": 7,
"price": 500,
"currency": "USD",
"status": "pending",
"usage": {
"plan": "unlimited",
"limit": null,
"used": 12,
"remaining": null,
"total": 340,
"unlimited": true,
"upgrade_price": null,
"upgrade_currency": null,
"upgrade_price_display": null,
"quota_reached": false
}
}
POST /api/v1/domains
Adds a domain. Body: { "domain": "yourdomain.com" }.
Request
curl -X POST -H "Authorization: Bearer mx2_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"yourdomain.com"}' \
"https://mx2api.com/api/v1/domains"
Response
{
"domain": "yourdomain.com",
"status": "pending",
"dns": {
"status": "pending",
"mx": null,
"mx_records": [],
"error": "ENOTFOUND",
"manual": false,
"attempts": 1,
"auto_check_active": true,
"auto_check_deadline": "2026-11-16T16:38:35.000Z"
},
"instructions": {
"mx": {
"type": "MX",
"name": "yourdomain.com",
"value": "mx.mx2api.com",
"note": "Point the MX record of your domain to this host - no TXT verification needed."
}
}
}
POST /api/v1/domains/:domain/verify
Re-checks the MX record of a domain (manual check).
Request
curl -X POST -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/domains/yourdomain.com/verify"
Response
{
"status": "active",
"dns": {
"status": "active",
"mx": "mx.mx2api.com",
"mx_records": [
{ "exchange": "mx.mx2api.com", "priority": 10 }
],
"error": null,
"manual": true,
"attempts": 4,
"auto_check_active": true,
"auto_check_deadline": "2026-11-16T16:38:35.000Z"
},
"instructions": {
"mx": {
"type": "MX",
"name": "yourdomain.com",
"value": "mx.mx2api.com",
"note": "Point the MX record of your domain to this host - no TXT verification needed."
}
}
}
GET /api/v1/domains/:domain/dns
Current MX state of a domain (read-only, does not change anything).
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/domains/yourdomain.com/dns"
Response
{
"domain": "yourdomain.com",
"status": "mx_mismatch",
"dns": {
"status": "mx_mismatch",
"mx": "mail.other-provider.com",
"mx_records": [
{ "exchange": "mail.other-provider.com", "priority": 10 }
],
"error": null
},
"instructions": {
"mx": {
"type": "MX",
"name": "yourdomain.com",
"value": "mx.mx2api.com",
"note": "Point the MX record of your domain to this host - no TXT verification needed."
}
}
}
DELETE /api/v1/domains/:domain
Removes a domain from your account.
Request
curl -X DELETE -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/domains/yourdomain.com"
Response
{
"ok": true
}
GET /api/v1/stats
Message counters per domain.
Request
curl -H "Authorization: Bearer mx2_YOUR_KEY" \ "https://mx2api.com/api/v1/stats"
Response
{
"by_domain": [
{ "domain": "yourdomain.com", "n": 12 }
]
}
Errors
401 — missing or invalid API key
{
"error": "unauthorized",
"message": "Invalid API key"
}
404 — unknown message / endpoint
{
"error": "not_found"
}
429 — rate limited
{
"error": "rate_limited",
"message": "Too many requests, please try again later"
}
How mail reaches the API
- Add your domain in the dashboard and point its MX record to
mx.mx2api.com. - Every address on that domain works:
[email protected],[email protected],[email protected]. - Mail is delivered to our SMTP server on port 25 and parsed into JSON — subject, sender, text, HTML and attachments.
- Read it back anytime via
GET /api/v1/messageswith your API key.