Mailcaff API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. You can generate API keys from the API Keys page.

        # Include this header in every request

        Authorization: Bearer your-api-key-here

Requests without a valid API key will receive a 401 Unauthorized response.

Base URL

https://mailcaff.com/api/v1

Verify Email

Verify the deliverability of a single email address. Returns reachability status, quality score, and detailed checks.

POST /api/v1/verify

Request

        curl -X POST https://mailcaff.com/api/v1/verify \

          -H "Authorization: Bearer your-api-key" \

          -H "Content-Type: application/json" \

          -d '{

            "email": "user@example.com",

            "mode": "power"

          }'

Request Fields

Field	Type	Required	Description
email	string	Yes	The email address to verify
mode	string	No	`power` (default): full SMTP verification, 2–60s. `quick`: syntax + MX check only, sub-500ms. Quick mode does not contact the mail server.

Response

        {

          "email": "user@example.com",

          "status": "valid",

          "quality_score": 100,

          "is_valid": true,

          "is_deliverable": true,

          "is_disposable": false,

          "is_role_account": false,

          "is_free_email": false,

          "can_connect_smtp": true,

          "mx_accepts_mail": true,

          "mode": "power",

          "response_ms": 1240

        }

Response Fields

Field	Type	Description
email	string	The email address that was verified
status	string	Reachability result: `valid`, `invalid`, `risky`, `unknown`, `disposable`, or `error`
quality_score	integer	Composite quality score from 0–100 (higher is better)
is_valid	boolean	Whether the email is confirmed deliverable
is_deliverable	boolean	SMTP server accepted the recipient
is_disposable	boolean	Temporary/disposable email provider
is_role_account	boolean	Role-based address (e.g. info@, support@)
is_free_email	boolean	Free email provider (e.g. Gmail, Yahoo, Outlook)
can_connect_smtp	boolean	SMTP connection was successful
mx_accepts_mail	boolean	Domain has valid MX records
mode	string	Verification mode used: `power` or `quick`
is_spam_trap	boolean	Detected as a known spam trap address (only present when true)
response_ms	integer	Verification time in milliseconds

Status Values

Value	Quality Score	Meaning
valid	90–100	Email exists and is deliverable
risky	40–85	Delivery uncertain. The domain may accept all emails, or SMTP signals are mixed. Score reflects confidence: 75+ is likely deliverable, below 50 is likely undeliverable
unknown	40–45	Could not determine reachability (server timeout, etc.)
disposable	0–10	Temporary/throwaway email address
invalid	5–10	Email does not exist or is not deliverable

Bulk Verify

Submit up to 500 emails for background verification. Returns a job ID to poll for results.

POST /api/v1/verify/bulk

Request

        curl -X POST https://mailcaff.com/api/v1/verify/bulk \

          -H "Authorization: Bearer your-api-key" \

          -H "Content-Type: application/json" \

          -d '{

            "emails": [

              "alice@example.com",

              "bob@company.org",

              "charlie@domain.net"

            ]

          }'

Response (202 Accepted)

        {

          "job_id": "550e8400-e29b-41d4-a716-446655440000",

          "total": 3,

          "status": "processing"

        }

Check Job Status

GET /api/v1/verify/bulk/{job_id}

        curl https://mailcaff.com/api/v1/verify/bulk/{job_id} \

          -H "Authorization: Bearer your-api-key"

Response (completed)

        {

          "job_id": "550e8400-...",

          "status": "completed",

          "total": 3,

          "processed": 3,

          "valid_count": 2,

          "invalid_count": 1,

          "risky_count": 0,

          "results": [

            { "email": "alice@example.com", "status": "valid", "quality_score": 100, ... },

            { "email": "bob@company.org", "status": "valid", "quality_score": 95, ... },

            { "email": "charlie@domain.net", "status": "invalid", "quality_score": 5, ... }

          ]

        }

Each object in results has the same fields as the single verify response.

Find Email

Find a person's email address given their name and company domain. Tests common patterns against the mail server.

POST /api/v1/find

Request

        curl -X POST https://mailcaff.com/api/v1/find \

          -H "Authorization: Bearer your-api-key" \

          -H "Content-Type: application/json" \

          -d '{

            "first_name": "John",

            "last_name": "Doe",

            "domain": "company.com"

          }'

Response (found)

        {

          "found": true,

          "email": "john.doe@company.com",

          "confidence": "high",

          "pattern": "first.last",

          "source": "learned",

          "response_ms": 3200

        }

Response (not found)

        {

          "found": false,

          "email": null,

          "confidence": null,

          "pattern": null,

          "source": null,

          "reason": "no_mx_records",

          "response_ms": 45

        }

Response Fields

Field	Type	Description
found	boolean	Whether a valid email was discovered
email	string\|null	The discovered email address
confidence	string\|null	`high` (SMTP verified), `medium` (likely valid), or `low` (best guess on catch-all domain)
pattern	string\|null	Pattern that matched (e.g. `first.last`, `flast`)
source	string\|null	How the email was found: `learned` (SMTP verified), `cache` (cached result), `mx_intel` (MX provider intelligence), `gravatar` (Gravatar match), `pattern_db` (known domain pattern), `scraped` (website scrape)
reason	string\|null	Explanation when not found: `no_mx_records`, `disposable_domain`, `catchall_detected`, `no_pattern_matched`
response_ms	integer	Search time in milliseconds

Confidence Levels

Value	Meaning
high	Email confirmed deliverable via SMTP verification
medium	Email likely valid based on domain pattern or catch-all with strong signals
low	Best statistical guess on a catch-all domain. The email format is likely correct but delivery cannot be verified

Bulk Find

Submit multiple leads for background email finding. Returns a job ID to poll for results.

POST /api/v1/find/bulk

Request

        curl -X POST https://mailcaff.com/api/v1/find/bulk \

          -H "Authorization: Bearer your-api-key" \

          -H "Content-Type: application/json" \

          -d '{

            "leads": [

              { "first_name": "John", "last_name": "Doe", "domain": "company.com" },

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

            ]

          }'

Response (202 Accepted)

        {

          "job_id": "660f9500-...",

          "total": 2,

          "status": "processing"

        }

Check Job Status

GET /api/v1/find/bulk/{job_id}

        curl https://mailcaff.com/api/v1/find/bulk/{job_id} \

          -H "Authorization: Bearer your-api-key"

Response (completed)

        {

          "job_id": "660f9500-...",

          "status": "completed",

          "total": 2,

          "processed": 2,

          "found_count": 1,

          "results": [

            { "first_name": "John", "last_name": "Doe", "domain": "company.com", "found": true, "email": "john.doe@company.com" },

            { "first_name": "Jane", "last_name": "Smith", "domain": "acme.org", "found": false, "email": null }

          ]

        }

Domain Finder

Find the company domain from just a company name. Returns the domain with MX validation so you know it handles email. Pair with the Email Finder to go from company name to email address.

POST /api/v1/find-domain

Request

        curl -X POST https://mailcaff.com/api/v1/find-domain \

          -H "Authorization: Bearer your-api-key" \

          -H "Content-Type: application/json" \

          -d '{

            "company_name": "Coolblue"

          }'

Response

        {

          "company_name": "Coolblue",

          "domain": "coolblue.nl",

          "has_mx": true,

          "has_website": true,

          "confidence": "high",

          "candidates_checked": 4,

          "status": "found",

          "response_ms": 620

        }

Response Fields

Field	Type	Description
company_name	string	The company name that was searched
domain	string\|null	Best matching domain found (null if none found)
has_mx	boolean	Whether the domain has MX records (accepts email)
has_website	boolean	Whether the domain has a live website
confidence	string	"high" (website + MX), "medium" (MX only), or "low" (website only)
candidates_checked	integer	Number of domain candidates tested
status	string	"found", "not_found", or "error"
response_ms	integer	Total processing time in milliseconds

Costs 1 credit per lookup. Tries common TLDs (.com, .nl, .de, .io, .eu, .co, .net, .org) and validates with DNS + HTTP checks.

Webhooks

Configure a webhook URL to receive notifications when bulk jobs complete. Set your webhook URL in API Keys & Settings.

Webhook Payload

        {

          "event": "bulk_job.completed",

          "job_id": "550e8400-...",

          "job_type": "verify",

          "status": "completed",

          "total": 100,

          "summary": {

            "valid": 72,

            "invalid": 15,

            "risky": 8,

            "disposable": 3,

            "unknown": 2

          }

        }

Events: bulk_job.completed and bulk_job.failed. Webhooks are HTTPS-only and delivered with a 10-second timeout.

Error Responses

All errors return a JSON object with an error field.

Status Code	Meaning
400	Bad request: missing or invalid parameters
401	Unauthorized: missing or invalid API key
404	Not found: job or resource doesn't exist
429	Rate limit exceeded: monthly credits exhausted
500	Server error: contact support
503	Maintenance mode: the service is temporarily unavailable. Retry after the period indicated in the response.

        # Example: rate limit exceeded

        {

          "error": "Monthly limit exceeded",

          "monthly_limit": 10000,

          "monthly_used": 10000,

          "resets_at": "2026-03-01T00:00:00Z"

        }

Plans & Rate Limits

API usage is limited by your monthly plan quota. Each verification or find request counts as one credit. Unused credits roll over for one month.

Plan	Monthly Credits	Price
Free	600	$0/month
Starter	10,000	$12/month
Growth	50,000	$49/month
Scale	250,000	$129/month

Unused credits from the previous month carry over automatically (up to 1x your plan limit), giving you up to 2x credits in any single month.