API docs

One POST request checks an address and returns a verdict, a 0–100 score and the reasons behind it. A free account gives you 100 checks a day: get your API key.

• Authentication
• Request
• Response
• Verdicts
• Reason codes
• Flags
• Errors
• Limits
• Examples
• Privacy

Authentication

Every request needs an API key. Sign in with your email to create one; it's shown once, so store it somewhere safe. Send it in the Authorization header:

Authorization: Bearer ls_your_key_here

An x-api-key: ls_your_key_here header works too. Keep keys on your server: anyone with a key can spend its quota. If a key leaks, revoke it on your account page; that takes effect within a minute.

Request

POST https://api.legitsignup.com/v1/check with a JSON body:

POST /v1/check
Authorization: Bearer ls_your_key_here
Content-Type: application/json

{ "email": "Jane.Doe+news@gmail.con" }

Send content-type: application/json. The body may be at most 1 KB and the address at most 320 characters. Addresses are only accepted in the body: a GET with the address in the URL is refused, because URLs end up in logs.

Response

A 200 response describes the address. This is a real response for the request above:

{
  "email": "Jane.Doe+news@gmail.con",
  "verdict": "invalid",
  "score": 0,
  "reasons": [
    { "code": "typo_suspected", "message": "Did you mean gmail.com?" },
    { "code": "no_mail_server", "message": "The domain does not exist." }
  ],
  "suggestion": "Jane.Doe+news@gmail.com",
  "canonical": "jane.doe+news@gmail.con",
  "flags": {
    "syntaxValid": true,
    "role": false,
    "freeProvider": false,
    "disposable": false,
    "typo": true,
    "dnsChecked": true,
    "mailServer": false,
    "nullMx": false,
    "burnerMx": false,
    "parked": false,
    "newDomain": false,
    "randomLocalPart": false
  }
}

Verdicts

No verdict means the mailbox exists. We never contact the recipient's mail server, so ok means the address is well-formed, its domain accepts email, and nothing about it looks fake.

Reason codes

Codes are stable; messages may change. Each code counts once.

Flags

Errors

Errors return { "error": { "code": "…", "message": "…" } }.

Limits

Free accounts get 100 checks a day, shared by all of the account's keys, and at most 30 requests a minute. The daily quota resets at midnight UTC. Requests rejected before checking (bad JSON, a missing email) don't count.

Every response to a request with a key reports the quota:

If the API is slow, unreachable or over quota, let the signup through. A missed check is cheaper than a lost user.

Examples

curl

curl -X POST https://api.legitsignup.com/v1/check \
  -H "authorization: Bearer $LEGITSIGNUP_KEY" \
  -H "content-type: application/json" \
  -d '{"email": "jane@gmial.com"}'

JavaScript (Node 18+)

async function checkEmail(email) {
  try {
    const res = await fetch("https://api.legitsignup.com/v1/check", {
      method: "POST",
      headers: {
        authorization: `Bearer ${process.env.LEGITSIGNUP_KEY}`,
        "content-type": "application/json",
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(3000),
    });
    if (!res.ok) return null; // fail open
    return await res.json();
  } catch {
    return null; // fail open
  }
}

const result = await checkEmail("jane@gmial.com");
if (result?.verdict === "invalid") {
  // ask the user to fix the address
} else if (result?.suggestion) {
  // show: Did you mean result.suggestion?
}

Python

import os
import requests

def check_email(email: str) -> dict | None:
    try:
        res = requests.post(
            "https://api.legitsignup.com/v1/check",
            json={"email": email},
            headers={"authorization": f"Bearer {os.environ['LEGITSIGNUP_KEY']}"},
            timeout=3,
        )
        res.raise_for_status()
        return res.json()
    except requests.RequestException:
        return None  # fail open

result = check_email("jane@gmial.com")
if result and result["verdict"] == "invalid":
    ...  # ask the user to fix the address

PHP

function check_email(string $email): ?array {
    $ch = curl_init('https://api.legitsignup.com/v1/check');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'authorization: Bearer ' . getenv('LEGITSIGNUP_KEY'),
            'content-type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(['email' => $email]),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 3,
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    return ($body !== false && $status === 200) ? json_decode($body, true) : null; // null = fail open
}

Privacy

We never store the addresses you check. DNS results are cached per domain for at most 24 hours, logs record the domain and the verdict, never the address, and checked domains are kept for 30 days to research their age. Responses are sent with cache-control: no-store.

Your own account email is stored so you can sign in, along with daily check counts. Deleting your account removes both.