REST API — always-on

MailGuard API Reference

Verify any email address in real time or upload millions in bulk. Simple REST API, JSON responses, no SDK required.

Base URLhttps://api.mailsguard.io

🔑 Authentication

All requests require an API key passed in the X-Api-Key header. You can create and manage API keys in your dashboard.

curl -X POST https://api.mailsguard.io/api/v1/verify \  -H "X-Api-Key: mg_live_xxxxxxxxxxxxxxxxxxxx" \  -H "Content-Type: application/json" \  -d '{"email": "test@example.com"}'

⚡

Quick Examples

curl -X POST https://api.mailsguard.io/api/v1/verify \  -H "X-Api-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{"email": "user@example.com"}'

Sample Response

{
  "email": "user@example.com",
  "status": "valid",
  "score": 92,
  "checks": {
    "syntax": true,
    "dns": true,
    "disposable": false,
    "role_based": false,
    "free_provider": true,
    "catch_all": false,
    "smtp": "valid"
  },
  "duration_ms": 420
}

📋 Endpoints

POST/api/v1/verifySingle Email Verify

Verify a single email address in real time.

Parameter	Type	Required	Description
`email`	string	Yes	The email address to verify.

POST/api/v1/jobsBulk Upload

Upload a CSV file of emails for async bulk verification.

Parameter	Type	Required	Description
`file`	file (CSV)	Yes	CSV file with one email per row (max 10 MB).

GET/api/v1/jobs/:idJob Status

Poll the status and results of a bulk job.

Parameter	Type	Required	Description
`id`	string (path)	Yes	The jobId returned from the bulk upload.

GET/api/v1/jobs/:id/downloadDownload Results

Download the completed bulk job results as a CSV.

Parameter	Type	Required	Description
`id`	string (path)	Yes	The jobId of a completed job.

📊 Verification Statuses

Every verification returns one of these statuses.

valid

Email exists and accepts mail.

invalid

Email does not exist or is undeliverable.

risky

Catch-all, role-based, or disposable address.

unknown

Could not determine (timeout or no SMTP response).

⚠️ Rate Limits & Error Codes

Rate Limits

Endpoint	Limit
`POST /verify`	60 req / min
`POST /jobs`	10 req / min
`All other`	200 req / 15 min

HTTP Error Codes

Code	Meaning
`401`	Missing or invalid API key
`422`	Invalid request body
`429`	Rate limit exceeded
`500`	Internal server error

Ready to integrate?

Get API Key — Free ← Back to Home