EN FR
Features How it works Pricing Contact Login
🕒 Last updated: October 14, 2026

Customer API: decide the fate of your email from your own server

Learn how the "Customer API" option of the Clean Mailbox interface sends your email to a URL you host, and how your server answers with the action to take: do nothing, tag or block.

id="usage">
⚠️

Beta feature: the customer API is currently in beta. Its behavior and interface may change, and some rough edges are possible. Feel free to send us your feedback.

What it is for

Clean Mailbox's filters rely on our engines and, with the Yara rules module, on patterns you write. The Customer API goes further: your own server makes the decision. For every email received by your domain, Clean Mailbox sends the message to an HTTPS URL that you host, and your server answers with what to do with it.

It's the right option when your decision depends on data Clean Mailbox doesn't have: your CRM (is the sender a known customer?), an internal supplier list, your own analysis engines, complex business rules, and so on.

⚠️

Email content: by enabling this option, the full content of your email is sent to the server whose URL you declare. Make sure that hosting meets your security and privacy requirements (GDPR in particular).

Declare your URL

In the Clean Mailbox interface, open your domain, then the Customer API menu. The module is reserved to domain administrators and must be enabled on the domain: if the menu entry isn't visible, contact us to have it enabled.

  1. Enter your API URL, for example https://api.example.com/clean-mailbox, then save.
  2. A signing secret is generated automatically and displayed on the page (Show then Copy buttons). You'll need it in your code to verify where requests come from.
  3. To remove the option, clear the field and save (or use Remove the API): the secret is deleted at the same time.

The URL must follow these rules:

💡

If you filter incoming connections by IP address, ask our support team for the list of Clean Mailbox analysis servers to allow. If the secret is regenerated (Generate a new secret button), the previous one stops working immediately: update your server right away.

The request sent by Clean Mailbox

Clean Mailbox sends an HTTPS POST to your URL. The body is the raw email, as it was received (headers then content, with the original encodings: base64, quoted-printable, etc.), up to 5 MB. Above that, the email isn't sent to the API and is delivered.

HeaderValue
Content-Typemessage/rfc822
X-CMB-API-Version1
X-CMB-Domainrecipient domain concerned
X-CMB-Recipientsrecipient addresses of this domain, comma-separated
X-CMB-Envelope-Fromenvelope sender (empty for a bounce message)
X-CMB-Client-IPIP address of the server that sent the email
X-CMB-Queue-Idqueue identifier (useful to report a case to us)
X-CMB-Timestampsending time, in Unix seconds
X-CMB-Signaturev1= followed by the signature

Verify the signature

Anyone who knows your URL can send it a request. To be certain a request comes from Clean Mailbox, your server must verify the signature of every call:

signature = hex( HMAC-SHA256( secret, timestamp + "." + body ) )
header    : X-CMB-Signature: v1=<signature>

where timestamp is the value of X-CMB-Timestamp and body the raw email received. Your server must:

  1. recompute the signature and compare it in constant time (hash_equals in PHP, hmac.compare_digest in Python);
  2. reject a request whose timestamp differs from the current time by more than a few minutes (replay protection);
  3. answer 401 in both cases: Clean Mailbox then delivers the email, you lose nothing.
⚠️

Never put the secret in the URL or in a public repository. Without signature verification, a third party could call your API pretending to be Clean Mailbox.

Actions: do nothing, tag, block

Your server has 2 seconds at most to answer. The action is chosen in the response, as JSON of 4 KB at most:

{ "action": "none | tag | block", "tag": "[Suspect]", "reason": "short text, optional" }
Your server's responseEffect on the email
204 No Content (no body), or 200 with {"action": "none"} Do nothing: the email is delivered normally.
200 with {"action": "tag", "tag": "[Suspect]"} Tag: the email is delivered, with [Suspect] added at the beginning of the subject.
200 with {"action": "block", "reason": "short text"} Block: the email is not delivered and the sender sees nothing. A copy is kept in your quarantine.
Any other response The email is delivered, nothing is modified.

Guarantees and timeouts

The API can never cause an email to be lost or held back by accident. Only a valid "block" response blocks; in every other case the email is delivered normally:

Example server

A minimal PHP example: it verifies the signature, then answers according to a test keyword found in the email. Replace the test logic with your own checks.

<?php
const CMB_SECRET = 'PASTE_THE_SECRET_HERE';

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_CMB_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_CMB_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $body, CMB_SECRET);

// Check the signature and the timestamp (5 minutes at most)
if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}

header('Content-Type: application/json');

if (str_contains($body, '[BLOCK-ME]')) {
    echo json_encode(['action' => 'block', 'reason' => 'test keyword']);
} elseif (str_contains($body, '[TAG-ME]')) {
    echo json_encode(['action' => 'tag', 'tag' => '[API test]']);
} else {
    echo json_encode(['action' => 'none']);
}

Test your setup

  1. Deploy this script on an HTTPS server (valid certificate) and set the secret shown in the interface.
  2. Declare its URL in your domain's Customer API page.
  3. Send an email to an address of the domain with [TAG-ME], then another with [BLOCK-ME] in the subject.
  4. Check that the first arrives with the [API test] tag and that the second is blocked (copy in quarantine).

If nothing happens, one of the contract's rules is probably not met (signature, certificate, timeout, HTTP code): the email is then delivered unmodified.

Follow the decisions

Emails handled by your API can be identified in the interface:

Frequently asked questions

How is it different from Yara rules?

Yara rules are patterns you write in the interface and that Clean Mailbox evaluates itself, with the inactive, audit and active statuses. The Customer API hands the decision to your server, so you can use your own data and logic. It has no "audit" mode: the action you return is applied. To test safely, answer none and log on your side.

What happens if my server is down?

Email is delivered normally, without going through your decision. It is neither held back nor lost.

Is a blocked email lost?

No. It is kept in your quarantine, where you can review it and restore it in case of a false positive.

Can I set the API for all my domains at once?

The URL is currently set domain by domain. A common URL for all of an account's domains is being considered for later.

Need help enabling the option?

Our support team can help you enable the Customer API on your domain and validate its configuration. Developing, hosting and keeping your server available remains your responsibility.

Contact Clean Mailbox →

Let's protect your mailbox.

Questions about the trial, setup, pricing, or a partnership? We're here — and we answer fast.

✓ 30-day free trial, no card required
✓ Works with any mail server
✓ Setup in under 5 minutess
✓ Infrastructure based in France 🇫🇷