Check an email or domain

Send a check and understand the request and response fields.

Send one email address or domain to POST /api/v1/check. A completed check uses one credit and returns an allow, review, or block action.

Request

cURL

curl -s -X POST 'https://signupscore.com/api/v1/check' \
  -H 'Authorization: Bearer ss_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"input":"name@example.com"}'

TypeScript

const response = await fetch('https://signupscore.com/api/v1/check', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIGNUPSCORE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ input: 'name@example.com' }),
});

if (!response.ok) {
  throw new Error(`SignupScore returned ${response.status}`);
}

const decision = await response.json();

Python

import os
import requests

response = requests.post(
    'https://signupscore.com/api/v1/check',
    headers={
        'Authorization': f"Bearer {os.environ['SIGNUPSCORE_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={'input': 'name@example.com'},
    timeout=5,
)
response.raise_for_status()
decision = response.json()

All three examples make the same request. Use whichever fits your backend.

Response

200 response

{
  "request_id": "01J...",
  "action": "block",
  "primary_reason": "DISPOSABLE",
  "reasons": ["DISPOSABLE"],
  "signals": {
    "disposable": true,
    "public_provider": false,
    "role_based": false,
    "suspicious": false,
    "privacy_relay": false,
    "alias_subaddress": false,
    "has_mx": true,
    "suggested_domain": null
  }
}

This example blocks a known disposable provider. Your integration usually needs only action. Keep the reasons when you want to explain or investigate the result.

Request fields

Field	Type	Required	Meaning
`input`	string	Yes	Email address or domain to check.
`check_mx`	boolean	No	Check MX records. Defaults to `true`.

Examples:

Input	Checks performed
`name@example.com`	Email and domain checks.
`example.com`	Domain checks only.
`name@example.com`, `check_mx: false`	Email and domain checks without looking up mail servers.

Do not send fields that are not listed above.

Response fields

Field	Meaning
`request_id`	ID for finding the same decision in logs or support.
`action`	`allow`, `review`, or `block`.
`primary_reason`	Main reason for the action, or `OK`.
`reasons`	All reason codes found during the check.
`signals`	Email and domain facts you can use for specific exceptions.

The same request_id is also returned in the X-Request-ID response header.