API Documentation

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "dedup": true,  // optional - remove duplicates before processing (saves credits)
  "callback_url": "https://your-server.com/webhook",  // optional
  "metadata": {"campaign": "newsletter"}  // optional
}

{
  "schema_version": "1.0",
  "job": {
    "id": "job_abc123xyz",
    "status": "pending",
    "total_count": 3,
    "created_at": "2026-01-30T12:00:00Z"
  }
}

curl -X POST https://api.mailodds.com/v1/jobs/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@emails.csv" \
  -F "dedup=true" \
  -F 'metadata={"campaign": "newsletter"}'

curl -X POST https://api.mailodds.com/v1/jobs/upload/presigned \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "large_list.csv", "content_type": "text/csv"}'

{
  "schema_version": "1.0",
  "upload": {
    "url": "https://s3.amazonaws.com/mailodds-uploads",
    "fields": {
      "key": "uploads/abc123/large_list.csv",
      "AWSAccessKeyId": "...",
      "policy": "...",
      "signature": "..."
    },
    "s3_key": "uploads/abc123/large_list.csv",
    "expires_in": 3600
  }
}

curl -X POST "${URL}" \
  -F "key=${KEY}" \
  -F "AWSAccessKeyId=${ACCESS_KEY_ID}" \
  -F "policy=${POLICY}" \
  -F "signature=${SIGNATURE}" \
  -F "file=@large_list.csv"

curl -X POST https://api.mailodds.com/v1/jobs/upload/s3 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"s3_key": "uploads/abc123/large_list.csv", "dedup": true}'

curl "https://api.mailodds.com/v1/jobs/job_abc123xyz/results?format=csv&filter=valid_only&dedup=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o valid_emails.csv

const eventSource = new EventSource(
  'https://api.mailodds.com/v1/jobs/job_xyz789/stream?token=mo_live_xxx'
);

eventSource.addEventListener('progress', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Progress: ${data.percent}%`);
});

eventSource.addEventListener('done', (e) => {
  console.log('Job completed!');
  eventSource.close();
});

{
  "event": "job.completed",
  "job": {
    "id": "job_abc123xyz",
    "status": "completed",
    "total_count": 1000,
    "summary": {
      "valid": 850,
      "invalid": 80,
      "catch_all": 40,
      "unknown": 20,
      "do_not_mail": 10
    }
  },
  "timestamp": "2026-01-30T12:05:00Z"
}

import { createHmac } from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

// Express example
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-mailodds-signature'];
  if (!verifyWebhook(JSON.stringify(req.body), sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // Process event...
  res.status(200).send('ok');
});

curl https://api.mailodds.com/v1/policies \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "policies": [
    {
      "id": 1,
      "name": "Strict Policy",
      "description": "Reject catch-all and role accounts",
      "is_default": true,
      "is_enabled": true,
      "rule_count": 3
    }
  ],
  "limits": {
    "max_policies": -1,
    "max_rules_per_policy": -1,
    "plan": "pro"
  }
}

curl -X POST https://api.mailodds.com/v1/policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Strict Policy",
    "description": "Reject catch-all emails",
    "is_default": true,
    "rules": [
      {
        "type": "status_override",
        "condition": {"status": "catch_all"},
        "action": {"action": "reject"}
      }
    ]
  }'

curl -X POST https://api.mailodds.com/v1/policies/from-preset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset_id": "strict", "name": "My Strict Policy"}'

curl -X POST https://api.mailodds.com/v1/policies/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": 1,
    "test_result": {
      "email": "test@catch-all-domain.com",
      "status": "catch_all",
      "action": "accept_with_caution"
    }
  }'

{
  "original": {
    "status": "catch_all",
    "action": "accept_with_caution"
  },
  "modified": {
    "status": "catch_all",
    "action": "reject"
  },
  "matched_rule": {
    "id": 1,
    "type": "status_override",
    "condition": {"status": "catch_all"}
  },
  "rules_evaluated": 3
}

curl -X POST https://api.mailodds.com/v1/jobs/job_abc123xyz/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "schema_version": "1.0",
  "job": {
    "id": "job_abc123xyz",
    "status": "cancelled",
    "total_count": 1000,
    "processed_count": 450,
    "cancelled_pending": 550,  // emails not validated due to cancellation
    "progress_percent": 45
  }
}

curl -X DELETE https://api.mailodds.com/v1/jobs/job_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "schema_version": "1.0",
  "deleted": true,
  "job_id": "job_abc123xyz"
}

curl "https://api.mailodds.com/v1/telemetry/summary?window=24h" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "schemaVersion": "1.0",
  "window": "24h",
  "generatedAt": "2026-01-31T12:00:00Z",
  "timezone": "UTC",
  "totals": {
    "validations": 12500,
    "creditsUsed": 12500
  },
  "rates": {
    "deliverable": 0.872,
    "reject": 0.084,
    "unknown": 0.044,
    "suppressed": 0.003
  },
  "topReasons": [
    {"reason": "smtp_failed", "count": 450},
    {"reason": "disposable", "count": 230}
  ],
  "topDomains": [
    {"domain": "gmail.com", "volume": 4500, "deliverable": 0.94}
  ]
}