API Documentation

Authentication

All API requests require an API key passed via the X-API-Key header.

Get your API key by signing up free.

# Include in every request
X-API-Key: ms_live_your_api_key_here

POST /api/v1/verify

Validate an email address with all 8 checks and get a risk score.

Request

POST https://mailsentry.dev/api/v1/verify
Content-Type: application/json
X-API-Key: your_key

{
  "email": "user@example.com"
}

Response

{
  "email": "user@example.com",
  "score": 95,
  "verdict": "valid",
  "checks": {
    "syntax": { "valid": true },
    "mx_records": { "valid": true, "records": ["mx1.example.com"] },
    "disposable": { "is_disposable": false },
    "role_based": { "is_role_based": false },
    "free_provider": { "is_free": false },
    "typo": { "has_typo": false, "suggestion": null },
    "smtp": { "valid": true, "catch_all": false }
  },
  "response_time_ms": 42
}

Score & Verdicts

Scoring Logic

The score starts at 100 and deductions are applied:

Bulk Validation

Validate hundreds or thousands of emails in a single request. Submit a list, receive a job ID, then poll for results or wait for a webhook callback.

Create a Bulk Job

POST https://mailsentry.dev/api/v1/bulk
Content-Type: application/json
X-API-Key: your_key

{
  "emails": [
    "jane@example.com",
    "bob@tempmail.org",
    "info@company.co"
  ]
}

Response (Job Created)

{
  "id": "job_abc123",
  "status": "processing",
  "total_emails": 3,
  "processed": 0,
  "created_at": "2026-03-18T12:00:00Z"
}

Get Job Results

GET https://mailsentry.dev/api/v1/bulk/job_abc123
X-API-Key: your_key

Response (Completed)

{
  "id": "job_abc123",
  "status": "completed",
  "total_emails": 3,
  "processed": 3,
  "results": [
    { "email": "jane@example.com", "score": 95, "verdict": "valid" },
    { "email": "bob@tempmail.org", "score": 12, "verdict": "invalid" },
    { "email": "info@company.co", "score": 72, "verdict": "caution" }
  ],
  "completed_at": "2026-03-18T12:00:04Z"
}

Each email in the results array includes the same score, verdict, and checks object as the single verify endpoint. Every email validated counts toward your monthly usage quota.

Email Finder

Find a person's most likely email address given their name and company domain. We generate common email patterns and verify each one via MX + SMTP checks.

Request

POST https://mailsentry.dev/api/v1/finder
Content-Type: application/json
X-API-Key: your_key

{
  "first_name": "Jane",
  "last_name": "Smith",
  "domain": "acme.com"
}

Response

{
  "email": "jane.smith@acme.com",
  "confidence": 94,
  "status": "found",
  "patterns_tested": 6,
  "domain": "acme.com"
}

Confidence Levels

If no valid pattern is found, the response returns "status": "not_found" with "email": null. Each finder search counts as one check toward your monthly quota.

Code Examples

JavaScript / Node.js

const response = await fetch("https://mailsentry.dev/api/v1/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "ms_live_your_key_here"
  },
  body: JSON.stringify({ email: "user@example.com" })
});

const result = await response.json();

if (result.score < 50) {
  console.log("Risky email — consider rejecting");
}

if (result.checks.typo.has_typo) {
  console.log("Did you mean:", result.checks.typo.suggestion);
}

Python

import requests

response = requests.post(
    "https://mailsentry.dev/api/v1/verify",
    json={"email": "user@example.com"},
    headers={"X-API-Key": "ms_live_your_key_here"}
)

result = response.json()
print(f"Score: {result['score']} — {result['verdict']}")

cURL

curl -X POST https://mailsentry.dev/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ms_live_your_key_here" \
  -d '{"email": "user@example.com"}'

Error Codes

Rate Limits

Rate Limit Headers

Every API response includes these headers so you can handle throttling programmatically:

// Example response headers
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1710763200
X-Monthly-Remaining: 48,234

Webhooks

Available on Pro plans and above. Configure a webhook URL in your dashboard to receive real-time notifications.

Supported Events

Webhook Payload

POST https://your-app.com/webhook

{
  "event": "bulk.completed",
  "timestamp": "2026-03-18T12:00:04Z",
  "data": {
    "job_id": "job_abc123",
    "total_emails": 500,
    "valid": 423,
    "invalid": 77
  }
}

Webhooks are sent as POST requests with a JSON body. Verify the X-MailSentry-Signature header to confirm the request came from MailSentry.

Best Practices

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch("/api/v1/verify", { ... });
    if (res.status !== 429 && res.status !== 500) return res.json();
    await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
  }
  throw new Error("Max retries reached");
}

Versioning

Current version: v1. All endpoints are prefixed with /api/v1/. Breaking changes will be announced at least 90 days in advance via email and dashboard notifications. Non-breaking additions (new response fields, new endpoints) are shipped continuously without version bumps.