Documentation

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 URLhttps://mx2api.com/api/v1
Auth headerAuthorization: Bearer mx2_xxxxxxxx
Content typeapplication/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

  1. Add your domain in the dashboard and point its MX record to mx.mx2api.com.
  2. Every address on that domain works: [email protected], [email protected], [email protected].
  3. Mail is delivered to our SMTP server on port 25 and parsed into JSON — subject, sender, text, HTML and attachments.
  4. Read it back anytime via GET /api/v1/messages with your API key.