API reference

GET /domains

List the domains

Permission: domains:read.

Responses

200 example

{
    "data": [
        {
            "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
            "name": "cliente.com",
            "verified_at": "2026-10-17T12:00:00Z",
            "mx_ok": true,
            "spf_ok": true,
            "dkim_ok": false,
            "last_checked_at": "2026-10-17T12:00:00Z",
            "catch_all": [
                "owner@gmail.com"
            ],
            "catch_all_channel_ids": [
                "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
            ],
            "spam_level": "normal",
            "created_at": "2026-10-17T11:00:00Z"
        }
    ]
}

POST /domains

Add a domain

Permission: domains:write. Generates the verification token and the DKIM key; read the domain to get the DNS records to create.

Body

{
    "name": "cliente.com"
}

Responses

201 example

{
    "data": {
        "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "name": "cliente.com",
        "verified_at": "2026-10-17T12:00:00Z",
        "mx_ok": true,
        "spf_ok": true,
        "dkim_ok": false,
        "last_checked_at": "2026-10-17T12:00:00Z",
        "catch_all": [
            "owner@gmail.com"
        ],
        "catch_all_channel_ids": [
            "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        ],
        "spam_level": "normal",
        "created_at": "2026-10-17T11:00:00Z"
    }
}

GET /domains/{id}

Get a domain and its DNS records

Permission: domains:read. dns_records are the records to create at your DNS provider: MX, SPF (TXT @), DKIM (TXT <selector>._domainkey) and the _mxproxy verification TXT.

Parameters

Responses

200 example

{
    "data": {
        "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "name": "cliente.com",
        "verified_at": "2026-10-17T12:00:00Z",
        "mx_ok": true,
        "spf_ok": true,
        "dkim_ok": false,
        "last_checked_at": "2026-10-17T12:00:00Z",
        "catch_all": [
            "owner@gmail.com"
        ],
        "catch_all_channel_ids": [
            "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        ],
        "spam_level": "normal",
        "created_at": "2026-10-17T11:00:00Z",
        "dns_records": [
            {
                "type": "MX",
                "host": "@",
                "value": "mx.mxproxy.dev",
                "priority": 10
            }
        ]
    }
}

PATCH /domains/{id}

Change the catch-all or the spam filter

Permission: domains:write. Send only the fields to change. An empty catch_all (and no catch-all channel) refuses mail to addresses without a forwarder.

Parameters

Body

{
    "catch_all": [
        "owner@gmail.com"
    ],
    "catch_all_channel_ids": [
        "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
    ],
    "spam_level": "normal"
}

Responses

200 example

{
    "data": {
        "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "name": "cliente.com",
        "verified_at": "2026-10-17T12:00:00Z",
        "mx_ok": true,
        "spf_ok": true,
        "dkim_ok": false,
        "last_checked_at": "2026-10-17T12:00:00Z",
        "catch_all": [
            "owner@gmail.com"
        ],
        "catch_all_channel_ids": [
            "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        ],
        "spam_level": "normal",
        "created_at": "2026-10-17T11:00:00Z"
    }
}

DELETE /domains/{id}

Delete a domain

Permission: domains:write. Takes its forwarders and SMTP credentials with it; mail to the domain is refused from then on.

Parameters

Responses

POST /domains/{id}/verify

Check the DNS now

Permission: domains:write. Looks up MX, SPF, DKIM and the verification TXT now and returns the result. DNS changes may take a few hours to propagate.

Parameters

Responses

200 example

{
    "data": {
        "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "name": "cliente.com",
        "verified_at": "2026-10-17T12:00:00Z",
        "mx_ok": true,
        "spf_ok": true,
        "dkim_ok": false,
        "last_checked_at": "2026-10-17T12:00:00Z",
        "catch_all": [
            "owner@gmail.com"
        ],
        "catch_all_channel_ids": [
            "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        ],
        "spam_level": "normal",
        "created_at": "2026-10-17T11:00:00Z"
    }
}

GET /domains/{id}/forwarders

List the forwarders of a domain

Permission: domains:read.

Parameters

Responses

200 example

{
    "data": [
        {
            "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
            "domain_id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
            "local_part": "sales",
            "destinations": [
                "ana@gmail.com",
                "bia@outlook.com"
            ],
            "enabled": true,
            "created_at": "2026-10-17T12:00:00Z",
            "channel_ids": [
                "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
            ]
        }
    ]
}

POST /domains/{id}/forwarders

Create a forwarder

Permission: domains:write. In effect at once. No destination only when the forwarder has at least one channel: it then sends only the summary.

Parameters

Body

{
    "local_part": "sales",
    "destinations": [
        "ana@gmail.com",
        "bia@outlook.com"
    ],
    "enabled": true,
    "channel_ids": [
        "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
    ]
}

Responses

201 example

{
    "data": {
        "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "domain_id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "local_part": "sales",
        "destinations": [
            "ana@gmail.com",
            "bia@outlook.com"
        ],
        "enabled": true,
        "created_at": "2026-10-17T12:00:00Z",
        "channel_ids": [
            "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        ]
    }
}

PATCH /forwarders/{id}

Change a forwarder

Permission: domains:write. Send only the fields to change; channel_ids replaces the whole list.

Parameters

Body

{
    "destinations": [
        "ana@gmail.com"
    ],
    "enabled": true,
    "channel_ids": [
        "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
    ]
}

Responses

200 example

{
    "data": {
        "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "domain_id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
        "local_part": "sales",
        "destinations": [
            "ana@gmail.com",
            "bia@outlook.com"
        ],
        "enabled": true,
        "created_at": "2026-10-17T12:00:00Z",
        "channel_ids": [
            "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        ]
    }
}

DELETE /forwarders/{id}

Delete a forwarder

Permission: domains:write. Mail to the address then goes to the catch-all, or is refused.

Parameters

Responses

GET /logs

Read the message log

Permission: logs:read. Newest first. For the next page, pass the next_before you got as before. Kept for 30 days.

Parameters

Responses

200 example

{
    "data": [
        {
            "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
            "domain_id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
            "direction": "inbound",
            "mail_from": "joao@loja.com.br",
            "rcpt": "contato@cliente.com",
            "destination": "ana@gmail.com",
            "subject": "Pedido 42",
            "size": 48213,
            "status": "accepted",
            "detail": "rspamd score 8.20",
            "created_at": "2026-10-17T12:00:00Z",
            "channel_id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
        }
    ],
    "next_before": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f"
}

POST your URL

The summary of a received email (webhook channel)

A webhook channel (created in the dashboard, under Channels) gets a POST with the summary of each email of the forwarders and the catch-all you picked it on. The full email never goes to the webhook: only sender, recipients, subject, the first lines of the text (up to 3,500 characters, from text/plain or the HTML without tags) and the names of the attachments.

• Only https:// and a public address: a URL that resolves to an internal network (loopback, private, link-local, CGNAT, cloud metadata) is refused.
• Redirects are not followed (the delivery fails): use the final URL.
• Timeout of 10 s. Answer 2xx quickly and process later.
• 5xx, 408, 429 (with Retry-After in seconds, if you like) and connection failures are retried after 1 min, 5 min, 15 min, 30 min, 1 h, 2 h and every 4 h, for up to 5 days. Any other 4xx (and a redirect) gives up at once. Everything shows up in Logs.
• Up to 60 summaries per hour per channel; the rest are not sent (skipped in the log). A message flagged as spam does not go to channels.
• A retry repeats the same id: use it to ignore duplicates.

Verifying the signature

The secret (whsec_...) is shown once, when the channel is created: store it. X-Mxproxy-Signature is sha256= followed by the hex HMAC-SHA256, with the secret, of <X-Mxproxy-Timestamp>.<body> (the timestamp, a dot and the raw body, byte for byte, before any JSON parsing). Compare in constant time and refuse a timestamp more than 5 minutes away (it stops the replay of an old POST).

PHP:

<?php
$secret = getenv('MXPROXY_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_MXPROXY_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_MXPROXY_SIGNATURE'] ?? '';

$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

if (! hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$summary = json_decode($body, true);
http_response_code(204);

Node (Express; the body must arrive raw):

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/mxproxy', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Mxproxy-Timestamp') ?? '';
  const signature = Buffer.from(req.get('X-Mxproxy-Signature') ?? '');
  const expected = Buffer.from(
    'sha256=' + crypto.createHmac('sha256', process.env.MXPROXY_WEBHOOK_SECRET).update(`${timestamp}.`).update(req.body).digest('hex'),
  );

  const valid = signature.length === expected.length && crypto.timingSafeEqual(signature, expected);
  if (!valid || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.sendStatus(401);
  }

  const summary = JSON.parse(req.body);
  res.sendStatus(204);
});

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)

@app.post('/mxproxy')
def mxproxy():
    timestamp = request.headers.get('X-Mxproxy-Timestamp', '')
    signature = request.headers.get('X-Mxproxy-Signature', '')
    body = request.get_data()  # raw bytes
    expected = 'sha256=' + hmac.new(os.environ['MXPROXY_WEBHOOK_SECRET'].encode(), timestamp.encode() + b'.' + body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature) or abs(time.time() - int(timestamp or 0)) > 300:
        abort(401)

    summary = request.get_json()
    return '', 204

Telegram and WhatsApp need nothing on your side: the summary arrives as a message from the platform’s bot or sending number (WhatsApp, beta).

Parameters

Body

{
    "id": "0192f0a0-7d1c-7b3e-9f00-5a1b2c3d4e5f",
    "received_at": "2026-10-17T14:06:40.123456Z",
    "domain": "cliente.com",
    "alias": "contato@cliente.com",
    "from": "João Silva <joao@loja.com.br>",
    "to": "string",
    "subject": "Pedido 42",
    "date": "2026-10-17T11:06:38-03:00",
    "text": "Olá,\n\nchegou o pedido 42.",
    "truncated": false,
    "attachments": [
        {
            "name": "nota.pdf",
            "content_type": "application/pdf",
            "size": 48213
        }
    ],
    "spam_score": 1.2
}

Responses