API Documentation

Authentication

All API endpoints (except auth) require an API key passed in the X-API-Key header.

curl -H "X-API-Key: your-api-key" https://api.mailpulse.dev/v1/verify

Email Verification

Verify if an email address is valid and deliverable.

POST /api/v1/verify
Content-Type: application/json
X-API-Key: your-api-key

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

Response:

{
  "success": true,
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 100,
    "reason": "Accepted",
    "usage": {
      "used": 5,
      "limit": 1000,
      "periodStart": "2024-04-01"
    }
  },
  "requestId": "req_1712425620000_abc123"
}

Domain Health Check

GET /api/v1/domain/example.com/health
X-API-Key: your-api-key

Response:

{
  "success": true,
  "data": {
    "domain": "example.com",
    "reputation": "unknown",
    "spamRate": null,
    "hasMx": true,
    "hasSpf": true,
    "hasDmarc": false,
    "mxRecords": [
      { "host": "mail.example.com", "priority": 10 }
    ],
    "details": {
      "spf": "v=spf1 include:_spf.google.com ~all",
      "spfError": null,
      "dmarc": null
    },
    "usage": {
      "used": 2,
      "limit": 500,
      "periodStart": "2024-04-01"
    }
  },
  "requestId": "req_1712425620000_abc123"
}

Warmup Schedule

Generate a tier-based warmup plan for a new sending domain. The schedule is organized into three tiers that align with email list segmentation best practices. Note: This generates a schedule only; actual warmup sending requires separate infrastructure.

Request Options:

POST /api/v1/warmup/schedule
Content-Type: application/json
X-API-Key: your-api-key

{
  "domain": "mail.yourdomain.com",
  "totalVolume": 3000,
  "days": 30
}

{
  "domain": "mail.yourdomain.com",
  "days": 30,
  "dailyVolume": 100
}

Response (Tier-based):

{
  "success": true,
  "data": {
    "domain": "mail.yourdomain.com",
    "totalDays": 30,
    "totalVolume": 3000,
    "dailyVolume": 133,
    "tiers": [
      {
        "name": "Safe Contacts",
        "days": "1-9",
        "dailyVolumeRange": "68-99",
        "totalVolume": 750,
        "description": "Recent engagers, purchasers, repliers - people who know you"
      },
      {
        "name": "Warm Prospects",
        "days": "10-21",
        "dailyVolumeRange": "101-119",
        "totalVolume": 1350,
        "description": "Historical engagement, recent opt-ins, moderate activity"
      },
      {
        "name": "Cold Prospects",
        "days": "22-30",
        "dailyVolumeRange": "121-133",
        "totalVolume": 900,
        "description": "No engagement, old contacts, unknown quality"
      }
    ],
    "actualTotal": 3011,
    "tips": [
      "Start with safe contacts (people who know you)",
      "Gradually increase volume over time",
      "Engage with opened emails (reply, click)",
      "Avoid spam triggers in subject lines",
      "Warm up new domains for at least 30 days",
      "Read our email segmentation guide for best results"
    ],
    "usage": {
      "used": 1,
      "limit": 100,
      "periodStart": "2024-04-01"
    }
  },
  "requestId": "req_1712425620000_abc123"
}

Note: GET /api/v1/warmup/schedule/:id is not yet implemented.

Error Responses

All errors follow a consistent format with error codes and suggestions.

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "API key required",
    "category": "auth",
    "suggestion": "Please provide a valid API key in the X-API-Key header"
  },
  "requestId": "req_1712425620000_abc123"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "category": "validation",
    "field": "email",
    "suggestion": "Please check your input and try again"
  },
  "requestId": "req_1712425620000_abc123"
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded",
    "category": "client",
    "suggestion": "Please wait before making another request"
  },
  "requestId": "req_1712425620000_abc123"
}

Rate Limiting

API endpoints are rate-limited to prevent abuse. Limits are per API key.