API Documentation

Integrate MailQA's powerful email testing and validation tools into your application

Getting Started

To use the MailQA API, you'll need an API key. You can generate one from your dashboard.

All API requests must include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Base URL: https://api.mailqa.com/v1

Authentication

All API endpoints require authentication using Bearer tokens. Include your API key in the Authorization header of every request.

curl -X POST https://api.mailqa.com/v1/verify-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/api/v1/verify-email

Verify if an email address is valid and deliverable

Request Body

string (required) - Email address to verify

Response Example

{
  "valid": true,
  "email": "user@example.com",
  "disposable": false,
  "role_based": false,
  "smtp_check": {
    "valid": true,
    "deliverable": true
  },
  "mx_records": ["mx1.example.com", "mx2.example.com"],
  "credits_remaining": 95
}

cURL

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

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://api.mailqa.com/v1/verify-email',
  { email: 'user@example.com' },
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {'email': 'user@example.com'}

response = requests.post(
    'https://api.mailqa.com/v1/verify-email',
    headers=headers,
    json=data
)

print(response.json())

POST/api/v1/spam-test

Analyze an email for spam triggers and get a deliverability score

Request Body

subject

string (required) - Email subject line

body

string (required) - Email body content (HTML or plain text)

from_email

string (required) - Sender email address

Response Example

{
  "spam_score": 2.5,
  "rating": "good",
  "deliverability": 92,
  "issues": [
    {
      "type": "warning",
      "message": "Subject line contains ALL CAPS",
      "impact": "low"
    }
  ],
  "recommendations": [
    "Add unsubscribe link",
    "Include physical address"
  ],
  "credits_remaining": 94
}

cURL

curl -X POST https://api.mailqa.com/v1/spam-test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your Newsletter",
    "body": "<html>...</html>",
    "from_email": "newsletter@example.com"
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://api.mailqa.com/v1/spam-test',
  {
    subject: 'Your Newsletter',
    body: '<html>...</html>',
    from_email: 'newsletter@example.com'
  },
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    'subject': 'Your Newsletter',
    'body': '<html>...</html>',
    'from_email': 'newsletter@example.com'
}

response = requests.post(
    'https://api.mailqa.com/v1/spam-test',
    headers=headers,
    json=data
)

print(response.json())

POST/api/v1/dns-check

Check SPF, DKIM, and DMARC records for a domain

Request Body

domain

string (required) - Domain to check

Response Example

{
  "domain": "example.com",
  "spf": {
    "valid": true,
    "record": "v=spf1 include:_spf.google.com ~all",
    "status": "pass"
  },
  "dkim": {
    "valid": true,
    "selector": "default",
    "status": "pass"
  },
  "dmarc": {
    "valid": true,
    "record": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
    "policy": "quarantine",
    "status": "pass"
  },
  "mx_records": ["mx1.example.com", "mx2.example.com"],
  "credits_remaining": 93
}

cURL

curl -X POST https://api.mailqa.com/v1/dns-check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://api.mailqa.com/v1/dns-check',
  { domain: 'example.com' },
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {'domain': 'example.com'}

response = requests.post(
    'https://api.mailqa.com/v1/dns-check',
    headers=headers,
    json=data
)

print(response.json())

Error Codes

The MailQA API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
`200`	Success - Request completed successfully
`400`	Bad Request - Invalid parameters or missing required fields
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient credits or plan limitations
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end

Rate Limits

Rate limits vary by plan:

Free Plan: 100 requests/day
Pro Plan: 10,000 requests/day
Elite Plan: Unlimited requests

When you exceed your rate limit, the API will return a 429 status code. Check the X-RateLimit-Reset header to see when your limit resets.

Support

Need help? Check out our support page or email us at support@mailqa.com

Ready to improve your email deliverability?

Join thousands of developers and teams who trust MailQA to test, validate, and optimize their email infrastructure.

Get Started Free →View Pricing →