Getting Started

You will need

• A team on the Professional plan or higher. The API is not available on lower plans, and a request from one is refused with plan_upgrade_required.
• An API key, created under Settings → API keys. The secret is shown once, at creation. It is stored hashed, so we cannot show it to you again — if you lose it, rotate the key.
• The scopes the endpoints you want need. A key only ever holds the scopes you grant it, narrowed by what your own role permits.

curl "https://api.mailneo.co/api/v2/me" \
  -H "X-API-Key: $MAILNEO_API_KEY"

Two equivalent headers

Send your key either way — pick whichever your HTTP client makes easy:

• X-API-Key: mk_live_...
• Authorization: Bearer mk_live_...

Sending both is fine only if they are identical. Two different credentials in one request is never legitimate, so it is refused with api_key_invalid rather than resolved to one of them.

Key format

mk_live_<keyId>_<secret><checksum>

• mk_live_ for live keys, mk_test_ for test keys. A whole token is 68 characters.
• The last 6 characters are a checksum. A truncated paste is rejected before we touch the database, so a mangled key fails fast and unambiguously with api_key_malformed.
• Only mk_live_<keyId> is ever displayed back to you. It contains no character of the secret.

A key is not a password

• Keep it server-side. Anything you put in a browser, a mobile app or a public repository is compromised.
• Its permissions follow its creator. If that person's role is narrowed, or they leave the team, the key narrows or stops working with role_insufficient — effective scopes are re-resolved continuously rather than frozen at creation, and a role change takes effect within a minute.
• Revocation is immediate and is not reversible.

Scopes on the published surface

Grant the narrowest set that does the job. There is deliberately no scope for the unified inbox and no scope that writes email account credentials — a permission that does not exist cannot be mis-granted.

{
  "data": [ /* ... */ ],
  "meta": {
    "request_id": "req_...",
    "has_more": true,
    "next_cursor": "cur_...",
    "synced_through": "2026-08-03T11:59:55Z"
  }
}

What meta carries

Parameters

The types and limits above are read from the specification. Each endpoint's own reference page lists the exact set it accepts — sort in particular is per-endpoint, not universal.

Treat cursors as opaque

A cursor is a cur_-prefixed string. It is not signed and holds no secret, but its encoding is not part of the contract: store it, send it back, and do not parse it.

Every way a cursor can be wrong — truncated, edited, from a different sort order — produces the single code cursor_invalid. One code means your sync client needs exactly one branch: discard the saved cursor and restart from the first page.

# First run: no watermark, walk every page.
curl "https://api.mailneo.co/api/v2/contacts?limit=100" \
  -H "X-API-Key: $MAILNEO_API_KEY"

# Follow meta.next_cursor until meta.has_more is false, then store the
# LAST meta.synced_through you saw.
curl "https://api.mailneo.co/api/v2/contacts?limit=100&cursor=$CURSOR" \
  -H "X-API-Key: $MAILNEO_API_KEY"

# Every run after that: only what changed.
curl "https://api.mailneo.co/api/v2/contacts?updated_since=$SYNCED_THROUGH" \
  -H "X-API-Key: $MAILNEO_API_KEY"

Three rules that keep a sync correct

• Upsert by id, never insert. The watermark is held 5 seconds behind real time so a row written during your request cannot slip between two runs. The cost of that safety is that you will occasionally see a row you already have.
• Store the watermark only after the last page. Saving it mid-walk and crashing loses every row you had not read yet.
• Deletes are invisible. A deleted row has no timestamp to be newer than your watermark, so it simply stops appearing. If your system needs to mirror deletions, reconcile with a full walk periodically.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This endpoint requires the \"contacts:read\" scope.",
    "doc_url": "https://www.mailneo.co/documentation/api/getting-started#insufficient_scope",
    "request_id": "req_..."
  },
  "meta": { "request_id": "req_..." }
}

Branch on code, not message

• code is a stable contract. A code may be added, but an existing one is never renamed or repurposed.
• type is the broad category, useful for a default handler.
• message is written for a human reading a log. It is not stable — do not parse it.
• param appears when one field is at fault, and names it.
• request_id identifies the request in our logs. Log it.

Authentication

Permission

Request

List parameters

Conflict

Limits

Generic

How a replay is decided

• The key is fingerprinted together with the method, path, parameters and body. Same key and same request within 24 hours replays the original response, with Idempotent-Replayed: true on it.
• Same key with a different request is idempotency_key_reused — that mismatch is a bug in the caller, not something to guess at.
• Same key while the first attempt is still running is request_in_flight, with Retry-After telling you when to try again. A stalled attempt is reclaimed after 90 seconds.
• Keys are scoped to your team and may be up to 255 characters.

Two limits

• Per key: the limiter admits 600 requests per 60 seconds. GET /usage separately reports your plan's documented allowance under api.requests_per_minute, which on lower plans is the smaller of the two. Pace against whichever is lower, and treat RateLimit-Remaining as the authoritative live figure.
• Per address, before authentication: 120 failed attempts per 60 seconds. Successful requests are not counted, so sharing an egress address with other customers — as every hosted automation platform does — cannot throttle you.

Headers on every response

The legacy X-RateLimit-* spellings are sent alongside these for older clients. Prefer the unprefixed names.

Backing off

Honour Retry-After when it is present, and use exponential backoff with jitter otherwise. Retry rate_limit_exceeded, service_unavailable and internal_error. Do not retry a invalid_request_error unchanged — it will fail identically every time.

Mailneo-Version

• A version is pinned to your key when the key is created and never moves on its own. A key minted today keeps today's behaviour until you opt it up.
• Send Mailneo-Version to override it for one request — this is how you test a new shape before re-pinning.
• An unrecognised value is version_unsupported, never a silent fallback. A client that asked for a version it did not get would misparse every response.
• The resolved version comes back on every authenticated response in the same header. Requests rejected before authentication completes do not carry it.
• A key created today is pinned to 2026-08-15. Every version that has ever shipped stays callable: 2026-08-15.

Headers on every delivery

• X-Mailneo-Signature — t=<timestamp>,v1=<hex>. The hex is HMAC-SHA256 of <timestamp>.<raw body> keyed with your secret.
• X-Mailneo-Timestamp — the same unix-seconds value that is inside the signature.
• X-Mailneo-Event — the catalog event name, so you can route without parsing the body.
• X-Mailneo-Event-Id — deduplicate on this. It is stable across every retry and across a manual replay, so seeing it twice means you have already handled this event.
• X-Mailneo-Replay — true when the delivery was triggered by hand rather than by the original event.

import crypto from "node:crypto";

// rawBody must be the unparsed bytes — express.raw({ type: "application/json" }).
function verify(rawBody, headers, secret) {
  const header = headers["x-mailneo-signature"] ?? "";
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=", 2))
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;

  // Both directions: a far-future timestamp is a forgery signal too.
  const age = Math.abs(Math.floor(Date.now() / 1000) - t);
  if (age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Two checks, not one

• Compare digests in constant time. A plain === leaks how much of a forged signature was correct, one byte at a time.
• Reject a timestamp more than 300 seconds from now, in both directions. Without it a captured delivery stays replayable forever, and a far-future timestamp is equally a forgery signal.

Retries and failures

• Answer 2xx as soon as you have durably accepted the event. Do the work afterwards — a slow handler burns the delivery timeout and gets retried.
• Anything else is retried on a backoff ladder. A 4xx other than 408 or 429 is treated as permanent and not retried, because it will fail the same way next time.
• An endpoint that fails continuously is switched off automatically and the team owner is emailed. Read disabled_reason on the endpoint to tell that apart from someone turning it off, and re-enable with PATCH { "active": true }.
• The delivery log records the status, your response body and the error for every attempt. It does not include the event payload — fetch the object from its own endpoint using the event id if you need it.