REST API · JSON

API Documentation

Mailstrand lets you check if an email is real and usable — directly from your app, form, or script. Send a POST request, get a JSON answer, 1 credit per validation.

Base URL

How it works

Get an API key

Send a POST request

Include your key in the x-api-key header.

Read the JSON response

Know instantly if the email is valid, disposable, or enrichable.

Quick start

Copy this command, replace YOUR_API_KEY, and run it in your terminal.

POST /api/v1/validate 1 credit

curl

Expected result: a JSON object with valid, score, and credits_remaining.

Authentication

Every API call (except registration) needs your secret API key in the request header. Treat it like a password — never expose it in frontend code or public repos.

Header name x-api-key

Where to get it Dashboard → Step 1

Content-Type application/json

Required headers

Content-Type: application/json
x-api-key: YOUR_API_KEY

POST /api/v1/validate 1 credit

Validate an email

Checks format, mail server (MX records), disposable domains, role accounts, and typo suggestions. Returns a score from 0 to 100. Invalid format costs 0 credits.

Request body

{
  "email": "contact@company.com"
}

Field	Type	Description
`email`	string	The address to validate. Required.

Response 200 OK

{
  "valid": true,
  "format_ok": true,
  "mx_found": true,
  "disposable": false,
  "role_account": false,
  "free_provider": true,
  "score": 100,
  "did_you_mean": null,
  "credits_remaining": 9
}

Field	Meaning
`valid`	`true` if the email passes all checks
`format_ok`	Correct syntax (user@domain.com)
`mx_found`	Domain has a mail server
`disposable`	`true` = temporary/throwaway email
`role_account`	`true` = info@, admin@, support@, etc.
`free_provider`	`true` = Gmail, Yahoo, Outlook, etc.
`did_you_mean`	Suggested fix if domain looks like a typo (or `null`)
`score`	0–100 trust score (higher = better)
`credits_remaining`	Your balance after this call

Code examples

example

POST /api/v1/validate/bulk 1 credit / email*

Bulk validate

Validate up to 50 emails in one request. Same fields as single validate. *Only emails with valid format are billed (1 credit each).

Request body

{
  "emails": [
    "john@gmail.com",
    "bad-email",
    "info@company.com"
  ]
}

Response 200 OK

{
  "count": 3,
  "credits_used": 2,
  "credits_remaining": 7,
  "results": [ ... ]
}

POST /api/v1/enrich 2 credits

Enrich an email

Identifies the email provider (Gmail, Outlook…) and whether it's personal or business. Use this after validation for segmentation or lead scoring.

Request body

{
  "email": "john@gmail.com"
}

Response 200 OK

{
  "domain": "gmail.com",
  "provider": "gmail",
  "type": "personal",
  "credits_remaining": 8
}

Field	Meaning
`domain`	Part after the @
`provider`	Detected provider (gmail, outlook, yahoo…)
`type`	`personal` or `business`
`credits_remaining`	Your balance after this call

Account endpoints

Manage your API key and check your balance. No credits consumed.

POST /auth/register Free

Create an account. Returns your API key and 10 free credits.

{ "email": "you@company.com" }

GET /auth/me Free

Returns your email, credits, plan, and API key. Requires x-api-key.

POST /auth/regenerate-key Free

Issues a new API key. The old one stops working immediately.

Errors & rate limits

60 requests / minute

1 credit per validate

50 max bulk size

2 credits per enrich

0 credit if bad format

Status	Meaning	What to do
400	Bad request — missing or invalid email	Check your JSON body
401	Invalid or missing API key	Copy key from dashboard
402	Insufficient credits	Buy credits
429	Rate limit exceeded	Wait 1 minute, then retry
500	Server error	Retry later or contact support