M Blacklist API

Overview

M Blacklist collects abuse observations from many independent websites, corroborates them, and publishes the confirmed result as a queryable API and as an incremental feed you can mirror locally. It exists so that a brute-force campaign blocked on one site is already known to the next one.

What is in the database

Endpoints at a glance

Conventions

• All requests and responses are application/json; POST bodies must be JSON with a matching Content-Type.
• All timestamps are ISO 8601 in UTC, e.g. 2026-07-28T09:14:02Z.
• Every JSON response carries X-MBL-Version: 1. A breaking change ships as a new path prefix (/v2), never as a silent change to /v1.
• Additive fields may appear at any time — parse defensively and ignore keys you do not know.
• Public GET endpoints send Access-Control-Allow-Origin: * and answer OPTIONS preflight, so browser clients work. Authenticated endpoints deliberately do not, because your API key must never be embedded in front-end code.

Quick start

The fastest useful call is a single IP lookup. No account, no key, no headers.

curl -s "https://black.majevski.com/v1/check?type=ip&value=203.0.113.5"

<?php
declare(strict_types=1);

/**
 * Returns true when the address is listed. Fails OPEN: any transport or
 * decoding problem yields false, so a legitimate visitor is never blocked
 * because the API was unreachable.
 */
function mbl_ip_listed(string $ip): bool
{
    $url = 'https://black.majevski.com/v1/check?' . http_build_query([
        'type'  => 'ip',
        'value' => $ip,
    ]);

    $ctx = stream_context_create([
        'http' => [
            'method'        => 'GET',
            'timeout'       => 3,
            'ignore_errors' => true,
            'header'        => "Accept: application/json\r\n"
                             . "User-Agent: my-app/1.0\r\n",
        ],
    ]);

    $body = @file_get_contents($url, false, $ctx);
    if (false === $body) {
        return false;
    }

    $data = json_decode($body, true);

    return is_array($data) && true === ($data['listed'] ?? null);
}

var_dump(mbl_ip_listed('203.0.113.5'));

const BASE = 'https://black.majevski.com';

async function mblIpListed(ip) {
  const url = `${BASE}/v1/check?type=ip&value=${encodeURIComponent(ip)}`;

  try {
    const res = await fetch(url, {
      headers: { Accept: 'application/json' },
      signal: AbortSignal.timeout(3000),
    });
    if (!res.ok) return false;          // fail open
    const data = await res.json();
    return data.listed === true;
  } catch {
    return false;                        // fail open
  }
}

console.log(await mblIpListed('203.0.113.5'));

{
  "query":  { "type": "ip", "value": "203.0.113.5" },
  "listed": true,
  "result": {
    "kind": "ip",
    "status": "confirmed",
    "categories": ["bruteforce"],
    "score": 72.5,
    "report_count": 14,
    "distinct_sites": 3,
    "first_seen": "2026-05-02T18:21:44Z",
    "last_seen": "2026-07-27T23:06:10Z",
    "matched": "203.0.113.0/24"
  }
}

Where to go next

1. Check subjects on demand

   Use /v1/check for one-off lookups and its batch form for up to 100 values per call.

2. Check e-mail addresses privately

   Use /v1/range/{prefix} so the address never leaves your server — see the worked example.

3. Mirror the data set

   Pull /v1/feed on a schedule and answer every lookup from your own database. See mirroring the feed.

4. Contribute back

   Register your domain, verify ownership, get a key and report what you block. Contribution is what keeps the data set useful.

Core concepts

Entries and statuses

Every subject in the database is one entry. Reports accumulate against it and drive its status.

Categories

Corroboration

A single site's opinion is not enough to list anything. An entry is promoted from pending to confirmed when either:

• at least 2 distinct verified sites have reported it (policy.corroboration_threshold), or
• a single site whose trust score is 80 or higher and has been pinned by an operator reports it (policy.auto_confirm_trust). Pinning is a deliberate switch in the admin panel; a score a site reached on its own never qualifies.

Two kinds are excluded from that shortcut entirely: ip_range and email_domain always wait for a second, distinct site — however trusted the reporter. One CIDR or one mail domain can take out a whole network or provider, so nobody gets to publish one unilaterally.

Score

Every entry carries a score from 0.00 to 100.00 derived from report volume, how many independent sites corroborated it, and recency. It decays as an entry goes quiet. Use it to grade your response: a high score justifies an outright block, a low one a CAPTCHA or extra scrutiny. Treat exact values as advisory, not as a stable API contract.

Trust score

Each reporting site has a trust score from 0 to 100. It rises with accepted reports and account age and falls — sharply — when a site reports protected infrastructure. Low trust means reports carry less weight; sustained abuse of the reporting endpoint results in suspension.

The automatic formula is deliberately capped below policy.auto_confirm_trust, so no amount of reporting will earn a site the right to publish without corroboration: “accepted” only means well-formed, and volume is trivially farmed with meaningless indicators. That right comes solely from an operator pinning the score by hand, and is intended for first-party sites the operator runs themselves.

Protected ranges

Reports targeting private, reserved, loopback or link-local space (RFC 1918, 127.0.0.0/8, 169.254.0.0/16, ::1, fc00::/7) and the published ranges of major infrastructure providers are rejected with reason protected_range. Such rejections count against the reporting site. Filter locally before submitting: never report an address you obtained from an untrusted proxy header.

The same guard covers major mail providers. An email_domain report for gmail.com, googlemail.com, outlook.com, hotmail.com, yahoo.com, icloud.com, proton.me, gmx.net, qq.com, the large transactional senders (sendgrid.net, mailgun.org, …) or any subdomain of them is refused with protected_range — blacklisting such a domain would silently blank a large share of the world's legitimate mail. Report the offending email_hash instead; individual addresses at those providers list normally.

Retention

An entry expires 90 days after the last corroborating report (policy.entry_ttl_days). Expired entries disappear from lookups and from the feed. If you mirror the feed, apply the same window locally so your copy does not outlive the source.

Authentication

Reading is anonymous. You need a key only to submit reports or to read /v1/account. A key also raises your read budget from 60 to 600 requests per minute.

Key format

An API key is a single opaque string:

mbl_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef0123456789abcdef
└┬─┘ └─────┬────┘ └───────────────────────┬──────────────────────┘
 │         │                              │
 │         │                              └─ secret, 48 lowercase hex
 │         └──────────────────────────────── prefix, 12 lowercase hex (public)
 └────────────────────────────────────────── fixed marker

The service stores only the prefix and an HMAC-SHA-256 of the secret. The full key is displayed exactly once, at creation time, and can never be retrieved again — if you lose it, revoke it and issue a new one.

Sending the key

Two equivalent headers are accepted. Send one, never both.

Authorization: Bearer mbl_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef0123456789abcdef

X-API-Key: mbl_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef0123456789abcdef

# Keep the key in the environment, never in a repository.
export MBL_KEY="mbl_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef0123456789abcdef"

curl -s https://black.majevski.com/v1/account \
     -H "Authorization: Bearer $MBL_KEY"

<?php
declare(strict_types=1);

$key = getenv('MBL_KEY') ?: '';

$ch = curl_init('https://black.majevski.com/v1/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $key,
        'Accept: application/json',
    ],
]);

$body   = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (200 !== $status) {
    // Inspect $body['error']['code'] — see the error table.
    throw new RuntimeException('Account lookup failed with status ' . $status);
}

$account = json_decode((string) $body, true);
echo $account['site']['domain'], ' — trust ', $account['site']['trust_score'], PHP_EOL;

// Server-side only. Never ship an API key to a browser:
// authenticated endpoints intentionally send no CORS headers.
const res = await fetch('https://black.majevski.com/v1/account', {
  headers: {
    'Authorization': `Bearer ${process.env.MBL_KEY}`,
    'Accept': 'application/json',
  },
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const account = await res.json();
console.log(account.site.domain, account.site.trust_score);

Scopes

A key missing the required scope gets 403 forbidden_scope. A valid, correctly scoped key on a site that has not completed domain verification, or that has been suspended, gets 403 site_unverified.

Getting a key

1. Register your domain

   Sites are registered by an administrator. You supply the domain in canonical form — lowercase, no scheme, no www., punycode for IDNs — and a contact address.

2. Prove ownership

   Publish either a DNS TXT record at _mblacklist.<your-domain> with the value mbl-verify=<token>, or a file at https://<your-domain>/.well-known/mblacklist-<token>.txt whose body is the token. DNS is checked first, and always works; the HTTP method needs ext-curl on the server, which lets the fetch be pinned to the address that was vetted for SSRF — where it is missing, that check reports http_verification_unavailable rather than fetching unpinned, and you should use the TXT record.

3. Copy the key once

   On verification a key is issued and shown a single time. Store it in an environment variable or a secrets manager — never in version control, never in client-side code.

Normalization & hashing

These rules are normative. The server applies exactly them, and any client that wants its hashes to match must apply exactly them too. A single stray space or an uppercase letter produces a completely different digest and a silent miss.

Derived identifiers

Every entry additionally carries two derived values you may need:

• value_hash = sha256(kind . ':' . value) — the stable identifier of an entry, returned by /v1/report. Note the literal colon and the fact that kind here is the canonical kind, so an e-mail is hashed as email_hash:<digest>, never as email:<address>.
• hash_prefix — the first 5 characters of value for email_hash, and the first 5 characters of value_hash for every other kind. This is the bucket the k-anonymity endpoint queries.

Reference implementation

<?php
declare(strict_types=1);

/** SHA-256 of a normalized e-mail address (64 lowercase hex). */
function mbl_email_hash(string $email): string
{
    return hash('sha256', strtolower(trim($email)));
}

/** Stable entry identifier: sha256("<kind>:<canonical value>"). */
function mbl_value_hash(string $kind, string $value): string
{
    return hash('sha256', $kind . ':' . $value);
}

/** Canonical IP text, or null when the input is not an IP address. */
function mbl_normalize_ip(string $ip): ?string
{
    $bin = @inet_pton(trim($ip));
    if (false === $bin) {
        return null;
    }

    // ::ffff:203.0.113.5 collapses to 203.0.113.5 here.
    $out = @inet_ntop($bin);

    return false === $out ? null : $out;
}

/** Canonical e-mail domain, or null when it cannot be normalized. */
function mbl_normalize_domain(string $domain): ?string
{
    $d = strtolower(trim($domain));
    $d = ltrim($d, '@');
    $d = (string) preg_replace('#^[a-z][a-z0-9+.\-]*://#', '', $d);
    $d = (string) preg_replace('#^www\.#', '', $d);
    $d = rtrim($d, '.');

    if ('' === $d || strlen($d) > 191) {
        return null;
    }
    if (!preg_match('/^[a-z0-9](?:[a-z0-9\-._]*[a-z0-9])?$/', $d)) {
        return null;
    }

    return $d;
}

/** CIDR reduced to network address + prefix length, or null. */
function mbl_normalize_cidr(string $cidr): ?string
{
    $parts = explode('/', trim($cidr), 2);
    if (2 !== count($parts)) {
        return null;
    }

    $bin = @inet_pton($parts[0]);
    if (false === $bin || !ctype_digit($parts[1])) {
        return null;
    }

    $bits = strlen($bin) * 8;              // 32 for IPv4, 128 for IPv6
    $len  = (int) $parts[1];
    if ($len < 0 || $len > $bits) {
        return null;
    }

    // Clear every host bit.
    for ($i = 0; $i < strlen($bin); $i++) {
        $keep     = max(0, min(8, $len - $i * 8));
        $mask     = 0 === $keep ? 0 : (0xFF << (8 - $keep)) & 0xFF;
        $bin[$i]  = chr(ord($bin[$i]) & $mask);
    }

    return inet_ntop($bin) . '/' . $len;
}

/** SHA-256 of a normalized e-mail address (64 lowercase hex). */
async function mblEmailHash(email) {
  const normalized = email.trim().toLowerCase();
  const bytes  = new TextEncoder().encode(normalized);
  const digest = await crypto.subtle.digest('SHA-256', bytes);

  return [...new Uint8Array(digest)]
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
}

/** Stable entry identifier: sha256("<kind>:<canonical value>"). */
async function mblValueHash(kind, value) {
  const bytes  = new TextEncoder().encode(`${kind}:${value}`);
  const digest = await crypto.subtle.digest('SHA-256', bytes);

  return [...new Uint8Array(digest)]
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
}

/** Canonical e-mail domain, or null. */
function mblNormalizeDomain(domain) {
  let d = domain.trim().toLowerCase()
    .replace(/^@+/, '')
    .replace(/^[a-z][a-z0-9+.-]*:\/\//, '')
    .replace(/^www\./, '')
    .replace(/\.+$/, '');

  if (!d || d.length > 191) return null;
  if (!/^[a-z0-9](?:[a-z0-9\-._]*[a-z0-9])?$/.test(d)) return null;

  return d;
}

// crypto.subtle requires a secure context (https or localhost).
// In Node.js: import { webcrypto as crypto } from 'node:crypto';

import hashlib


def mbl_email_hash(email: str) -> str:
    """SHA-256 of a normalized e-mail address (64 lowercase hex)."""
    normalized = email.strip().lower()
    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()


def mbl_value_hash(kind: str, value: str) -> str:
    """Stable entry identifier: sha256("<kind>:<canonical value>")."""
    return hashlib.sha256(f"{kind}:{value}".encode("utf-8")).hexdigest()


def mbl_normalize_ip(ip: str):
    """Canonical IP text, or None."""
    import ipaddress
    try:
        addr = ipaddress.ip_address(ip.strip())
    except ValueError:
        return None
    # IPv4-mapped IPv6 collapses to dotted IPv4, matching inet_ntop().
    if addr.version == 6 and addr.ipv4_mapped is not None:
        return str(addr.ipv4_mapped)
    return str(addr)


print(mbl_email_hash("  Alice@Example.COM "))
# ff8d9819fc0e12bf0d24892e45987e249a28dce836a85cad60e28eaaa8c6d976

# Normalize, then hash. Note printf, not echo: a trailing newline
# would change the digest completely.
email='  Alice@Example.COM '

normalized=$(printf '%s' "$email" \
  | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' \
  | tr '[:upper:]' '[:lower:]')

printf '%s' "$normalized" | shasum -a 256 | cut -d' ' -f1
# ff8d9819fc0e12bf0d24892e45987e249a28dce836a85cad60e28eaaa8c6d976

# GNU/Linux: use sha256sum instead of shasum -a 256.

Test vectors

Verify your implementation against these before going near production. If any of them differs, your lookups will silently return “not listed” forever.

value_hash vectors

The k-anonymity e-mail flow

Checking an e-mail address against a remote blocklist normally means sending the address — or its full hash, which is just as identifying for a known address — to a third party. M Blacklist avoids that entirely.

You hash the address locally, send only the first 5 hex characters of the digest, and receive every listed digest sharing that bucket. The final comparison happens on your machine. A 5-character prefix covers 16⁵ = 1 048 576 buckets, so the request tells the server nothing beyond “one of roughly a millionth of the address space”, and the answer is byte-for-byte identical for every address in that bucket.

  YOUR SERVER                                    black.majevski.com
  ───────────                                    ──────────────────

  "  Alice@Example.COM "
        │
        │  1. trim + lowercase
        ▼
  "alice@example.com"
        │
        │  2. sha256
        ▼
  ff8d9 819fc0e12bf0d24892e45987e249a28dce836a85cad60e28eaaa8c6d976
  └─┬─┘ └──────────────────────────┬──────────────────────────────┘
    │                              │
    │  3. send prefix only         │  never leaves your server
    ▼                              │
  GET /v1/range/ff8d9 ─────────────┼──────────────►  bucket lookup
                                   │                        │
  4. receive every suffix in       │                        │
     the bucket  ◄─────────────────┼────────────────────────┘
        │                          │
        │  5. compare locally      │
        ▼                          ▼
  suffix in response? ────────► LISTED / NOT LISTED

Worked example

1. Normalize

   The raw input "  Alice@Example.COM " becomes alice@example.com after trim() and strtolower(). Nothing else is changed — no plus-address stripping, no dot removal.

2. Hash

   sha256("alice@example.com") is:

   ff8d9819fc0e12bf0d24892e45987e249a28dce836a85cad60e28eaaa8c6d976

   The first 5 characters (ff8d9) are the prefix; the remaining 59 are the suffix.

3. Request the bucket

   curl -s "https://black.majevski.com/v1/range/ff8d9?type=email"

   Only ff8d9 was transmitted. The server cannot tell whether you asked about alice@example.com or any of the roughly 2²³⁶ other strings that hash into the same bucket.

4. Receive every candidate

   {
     "prefix": "ff8d9",
     "type": "email",
     "count": 3,
     "suffixes": [
       { "suffix": "819fc0e12bf0d24892e45987e249a28dce836a85cad60e28eaaa8c6d976",
         "status": "confirmed", "categories": ["fake_account","spam"],
         "score": 61.0, "last_seen": "2026-07-26T12:40:31Z" },
       { "suffix": "cc05ccd3815abaddae9971aeeb904fd1fe0402a9747fc00854374a706d0",
         "status": "confirmed", "categories": ["spam"],
         "score": 44.25, "last_seen": "2026-07-19T04:02:57Z" },
       { "suffix": "d1010a46efd74417334df7f0dfc8d84bfaba8907bd33a0fdd2ef3cf4672",
         "status": "confirmed", "categories": ["abuse"],
         "score": 55.75, "last_seen": "2026-07-24T16:33:08Z" }
     ]
   }

5. Compare locally

   Your suffix is 819fc0e12bf0d24892e45987e249a28dce836a85cad60e28eaaa8c6d976. It is the first entry in the response, so alice@example.com is listed, with categories fake_account and spam and a score of 61.0. Had it not appeared, the answer would be “not listed”, and the other two suffixes tell you nothing about which addresses they belong to — they are one-way digests.

   Use a constant-time comparison (hash_equals() in PHP) so your own process leaks no timing signal about which address was checked.

Mirroring the feed

For anything on a request-handling hot path — a firewall, a login form, a registration check — do not call the API synchronously. Mirror the feed on a schedule and answer from your own database. That gives you O(1) lookups, no third-party latency, and correct behaviour when the network is down.

1. Store a cursor, not a guess

   Keep the server_time from your last completed sync. Pass it as since on the next run's first request, then follow next_cursor until it is null. Only update your stored timestamp after a run completes — a partial run must be safe to repeat.

2. Upsert by (kind, value)

   Entries reappear in the feed whenever they are updated, so your writer must be idempotent. Index IP ranges as binary start/end pairs so a lookup is a single indexed range query, and remember that IPv4 and IPv6 values must be compared within the same address family.

3. Expire locally too

   The feed only contains confirmed entries; an entry that is delisted, removed or expired simply stops appearing. Prune local rows whose last_seen is older than the 90-day retention window so your mirror never outlives the source.

4. Sync at a sane interval

   Hourly to every six hours is right for almost everyone. Add jitter so a fleet of clients does not stampede on the hour. Back off on 429 and 5xx, and never retry in a tight loop.

5. Bound everything

   Cap the number of pages per run, cap your local table size, and cap the report queue you push back. A sync job that can grow without limit is an outage waiting for a busy week.

See the PHP and JavaScript sync loops in the /v1/feed section for complete, bounded implementations.

Rate limits

Limits are enforced in a fixed 60-second window. Anonymous reads are counted per client IP; authenticated requests are counted per API key.

Headers

Every response carries the state of your current window:

HTTP/1.1 200 OK
X-MBL-Version: 1
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1785315300

X-RateLimit-Reset is a Unix timestamp. When the budget is exhausted the service answers 429 and adds Retry-After in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 27
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785315300

{"error":{"code":"rate_limited","message":"Rate limit exceeded. Retry after 27 seconds."}}

Staying inside the budget

• Batch: POST /v1/check with 100 values is one request, not 100.
• Cache: hold lookup answers for at least a few minutes, and range buckets for up to 24 hours.
• Mirror: the feed removes per-lookup traffic entirely.
• Honour Retry-After. Add exponential backoff with jitter on 429 and 5xx; never retry a 4xx other than 429.
• Behind a proxy or CDN, anonymous limits are counted per client IP only when the proxy is on the service's trusted list — otherwise your whole fleet shares one bucket. Use a key.

Error codes

Every non-2xx response uses one envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "Parameter \"type\" must be one of: ip, email, email_hash, domain."
  }
}

Branch on error.code, which is stable. error.message is human-readable, may change wording, and never contains internal detail such as SQL, stack traces or file paths.

Recommended client behaviour

Privacy statement

M Blacklist is a security service, which makes it exactly the kind of system that must be careful with personal data rather than exempt from caring. The design below is the guarantee; it is enforced in code, not by policy alone.

E-mail addresses are never stored in plaintext

• An address is only ever persisted as sha256(strtolower(trim(address))) — plus, when the operator has configured an encryption key, an AES-256-GCM ciphertext for the admin panel's moderation screen. That key lives in the server configuration file, never in the database, so neither column can yield an address from a database dump alone. No column anywhere in the schema can hold a plaintext address.
• When you submit type=email or kind=email, the address is hashed in memory during request handling and discarded. It is not written to the database, not written to an application log, and not echoed in the response — /v1/check returns query.value_hash and deliberately omits query.value.
• The same rule applies to appeals: an appeal record stores the digest, never the address that produced it.
• Because SHA-256 is one-way, the service cannot recover an address from its stored form, and neither can anyone who obtains a copy of the database.

What is stored

What is never stored

• Plaintext e-mail addresses, in any table, log or backup.
• Passwords, password hashes or session tokens belonging to reported users.
• Message bodies, form submissions, request bodies or cookies.
• Names, postal addresses, phone numbers or payment data.
• Browsing history, or any behavioural profile of an end user. Reports are single-event observations, not a timeline.
• API key secrets. Only a keyed HMAC of the secret is stored.

Your obligations as an integrator

• Report only what you actually observed on your own infrastructure. Never forward data obtained from a third party.
• Prefer email_hash over email and prefer the range endpoint over both, so the address never leaves your systems.
• Keep personal data out of evidence. Counts, timestamps, rule names and target paths are enough.
• Tell your users, in your own privacy notice, that abusive submissions may be reported to a shared threat-intelligence service in hashed form.
• Do not use the service to make consequential decisions about a person without a human review path. Automated blocking should always be appealable.

Delisting

Anyone can request removal through POST /v1/appeal without an account. An e-mail listing can be appealed using only its digest, so exercising the right does not require disclosing the address. Approved appeals set the entry to removed, which takes it out of lookups and out of the feed on the next sync.

Transport and access

• HTTPS only, with HSTS. There is no plaintext endpoint.
• Authenticated endpoints send no permissive CORS headers, so a key cannot be used from a browser page and cannot leak through one.
• All database access uses prepared statements; all secret comparisons are constant-time; administrative access is session-authenticated with CSRF protection on every state change.

FAQ

Changelog

Compatibility policy

• Fields may be added to any response without notice. Ignore keys you do not recognise rather than failing.
• Fields are never removed or repurposed within /v1. A breaking change ships as /v2, and /v1 keeps working through a published deprecation window announced on this page.
• error.code values and entry kind, status and category values are stable. New members may be added to those sets; handle unknown members gracefully.
• Numeric score values are advisory and their formula may be tuned. Do not hard-code exact thresholds you cannot revisit.