Getting started

Quick start

MailGuard verifies emails using real SMTP handshakes — not just DNS lookups. Get started in under 2 minutes.

Step 1

Get an API key

Step 2

Make a request

Send a GET request with your email and API key. Response in under 2 seconds.

Step 3

Use the result

Check the status field — valid, invalid, risky, or unknown.

bash

curl "https://api.mailguard.in/v1/verify?email=ravi@acme.com" \
  -H "x-api-key: mg_live_your_key_here"

Authentication

All requests need your API key in the x-api-key header. Generate keys from your dashboard.

bash

# Correct — key in header
curl "https://api.mailguard.in/v1/verify?email=test@gmail.com" \
  -H "x-api-key: mg_live_VXrukNIZihu..."

Each successful verification costs 1 credit. Never expose your API key in frontend JavaScript.

Endpoints

GET/api/v1/verify

Verify a single email address in real-time via full SMTP handshake.

Auth: x-api-key header

Parameters

emailstringrequiredThe email address to verify

Request

bash

curl "https://api.mailguard.in/v1/verify?email=ravi@acme.com" \
  -H "x-api-key: mg_live_your_key_here"

Response

json

{
  "email": "ravi@acme.com",
  "status": "valid",
  "sub_status": null,
  "score": 94,
  "is_disposable": false,
  "is_catch_all": false,
  "mx_record": "mail.acme.com",
  "checked_at": "2026-05-10T03:25:40Z",
  "cached": false
}

Status codes

Every response includes a status field:

valid

Mailbox exists — safe to send.

invalid

Mailbox does not exist or domain has no MX record.

risky

Catch-all domain — accepts all addresses, deliverability uncertain.

unknown

SMTP timeout or greylisted — try again later.

Sub statuses

The sub_status field provides detail when status is not valid:

Code	Description
`disposable`	Throwaway email provider (mailinator, guerrillamail, etc.)
`catch_all`	Domain accepts all addresses regardless of mailbox existence
`no_mx_record`	Domain has no mail server configured
`invalid_syntax`	Email format is malformed (RFC 5321)
`greylisted`	Server temporarily rejected — retry after 5 minutes
`smtp_timeout`	Mail server did not respond within 10 second timeout

Rate limits

Free

100 req/min

100 total

Pro

300 req/min

50K/month

Business

1,000 req/min

2L/month

Rate limited requests receive HTTP 429. Use exponential backoff starting at 1s.

Error handling

json

{ "error": "email is required" }          // 400 Bad request
{ "error": "Invalid API key" }            // 401 Unauthorized
{ "error": "Insufficient credits" }       // 402 Payment required
{ "error": "Too many requests" }          // 429 Rate limited
{ "error": "Internal server error" }      // 500 Server error

SDKs & integrations

cURLavailable

curl "https://api.mailguard.in/v1/verify?email=ravi@acme.com" \
  -H "x-api-key: mg_live_your_key"

Node.jscoming soon

// npm install @mailguard/node (coming soon)
const mg = require('@mailguard/node')
const result = await mg.verify('ravi@acme.com')

Pythoncoming soon

# pip install mailguard (coming soon)
import mailguard
result = mailguard.verify("ravi@acme.com")

PHPcoming soon

// composer require mailguard/php (coming soon)
$mg = new MailGuard\Client($apiKey);
$result = $mg->verify('ravi@acme.com');