Whether you are validating emails at signup or cleaning a bulk list, the MailsGuard API makes it straightforward. This tutorial covers single-email verification, bulk processing, and best practices for both Node.js and Python.
Before you start
You need a MailsGuard API key. Create a free account → — 100 free credits, no card required.
API basics
The MailsGuard API is a simple REST API. All requests use HTTPS. Authentication is via an API key in the X-Api-Key header.
Base URL: https://api.mailsguard.io/api/v1 Auth: X-Api-Key: YOUR_API_KEY Format: JSON (Content-Type: application/json)
Single email verification
Node.js (fetch)
const API_KEY = 'mg_live_your_key_here'
async function verifyEmail(email) {
const response = await fetch('https://api.mailsguard.io/api/v1/verify', {
method: 'POST',
headers: {
'X-Api-Key': API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email }),
})
if (!response.ok) {
const error = await response.json()
throw new Error(error.error?.message ?? `HTTP ${response.status}`)
}
return response.json()
}
// Usage
const result = await verifyEmail('user@example.com')
console.log(result.status) // 'valid' | 'invalid' | 'risky' | 'unknown'
console.log(result.score) // 0-100 confidence score
console.log(result.checks) // detailed breakdownPython (requests)
import requests
API_KEY = 'mg_live_your_key_here'
def verify_email(email: str) -> dict:
response = requests.post(
'https://api.mailsguard.io/api/v1/verify',
headers={
'X-Api-Key': API_KEY,
'Content-Type': 'application/json',
},
json={'email': email},
)
response.raise_for_status()
return response.json()
# Usage
result = verify_email('user@example.com')
print(result['status']) # 'valid' | 'invalid' | 'risky' | 'unknown'
print(result['score']) # 0-100 confidence score
print(result['checks']) # detailed breakdownUnderstanding the response
{
"email": "user@example.com",
"status": "valid",
"score": 92,
"reason": null,
"checks": {
"syntax": true,
"dns": true,
"disposable": false,
"role_based": false,
"free_provider": true,
"catch_all": false,
"smtp": "valid"
},
"verified_at": "2026-05-31T10:00:00.000Z",
"duration_ms": 420
}The status field is the main result. Use score for borderline cases — a score above 70 is generally safe to send to.
Validating at signup
The most common use case is real-time validation on a signup form. Here is how to do it in Node.js with Express:
import express from 'express'
const app = express()
app.use(express.json())
app.post('/signup', async (req, res) => {
const { email, name } = req.body
// Verify email before creating account
const verification = await verifyEmail(email)
if (verification.status === 'invalid') {
return res.status(400).json({
error: 'That email address does not exist. Please check and try again.',
})
}
if (verification.checks.disposable) {
return res.status(400).json({
error: 'Please use a real email address, not a temporary one.',
})
}
// Email is valid — proceed with account creation
await createUser({ email, name })
res.json({ success: true })
})Bulk verification via API
For lists of 10+ emails, use the bulk jobs endpoint. Upload a CSV and poll for results:
import FormData from 'form-data'
import fs from 'fs'
import fetch from 'node-fetch'
async function verifyBulk(csvPath) {
const form = new FormData()
form.append('file', fs.createReadStream(csvPath))
// Upload the file
const uploadRes = await fetch('https://api.mailsguard.io/api/v1/jobs', {
method: 'POST',
headers: { 'X-Api-Key': API_KEY, ...form.getHeaders() },
body: form,
})
const { jobId } = await uploadRes.json()
console.log('Job started:', jobId)
// Poll until complete
while (true) {
await new Promise(r => setTimeout(r, 3000)) // wait 3 seconds
const statusRes = await fetch(
`https://api.mailsguard.io/api/v1/jobs/${jobId}`,
{ headers: { 'X-Api-Key': API_KEY } }
)
const job = await statusRes.json()
if (job.status === 'completed') {
console.log(`Done: ${job.validCount} valid, ${job.invalidCount} invalid`)
break
}
if (job.status === 'failed') {
throw new Error('Job failed: ' + job.errorMessage)
}
const pct = Math.round((job.processedEmails / job.totalEmails) * 100)
console.log(`Progress: ${pct}%`)
}
}Error handling
The API uses standard HTTP status codes. Handle these in your integration:
200 OK — Success 400 Bad Request — Invalid input (check error.message) 401 Unauthorized — Invalid or missing API key 402 Payment — Insufficient credits 429 Too Many — Rate limit exceeded (retry after header) 500 Server Error — Retry with exponential backoff
Rate limits
Single verification: 60 requests per minute per API key. Bulk upload: 5 jobs per hour. If you need higher limits, contact us.