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}
  ]
}

{
  "domain": {
    "id": "d8f3a1b2-4c5e-6f7a-8b9c-0d1e2f3a4b5c",
    "domain": "yourdomain.com",
    "domain_type": "ns_delegated",
    "status": "pending_dns",
    "dkim_selector": "mo1",
    "dns_records": {
      "ns": {
        "type": "NS",
        "host": "mo.yourdomain.com",
        "targets": [
          "ns1.mailodds.net",
          "ns2.mailodds.net",
          "ns3.mailodds.net",
          "ns4.mailodds.net"
        ],
        "status": "pending",
        "verified_at": null
      }
    },
    "created_at": "2026-02-25T12:00:00Z",
    "updated_at": "2026-02-25T12:00:00Z"
  }
}

{
  "identity_score": {
    "overall_score": 95,
    "checks": {
      "dkim":        { "status": "pass", "score": 20 },
      "spf":         { "status": "pass", "score": 20 },
      "dmarc":       { "status": "pass", "score": 25, "policy": "reject" },
      "mx":          { "status": "pass", "score": 15 },
      "return_path": { "status": "pass", "score": 15 }
    }
  }
}

{
  "message_id": "msg_abc123xyz",
  "status": "queued",
  "recipients": 1,
  "suppressed": [],
  "validation": {
    "checked": true,
    "results": {}
  },
  "delivery": {
    "pool": "standard",
    "lane": "green",
    "queued_at": "2026-02-25T12:00:00+00:00"
  },
  "content_scan": {
    "action": "allow",
    "score": 0.1
  }
}

{
  "total": 2,
  "accepted": 2,
  "rejected": [],
  "status": "queued",
  "delivery": {
    "pool": "standard",
    "lane": "green",
    "queued_at": "2026-02-25T12:00:00+00:00"
  }
}

{
  "stats": {
    "period": "30d",
    "sent": 12500,
    "delivered": 12350,
    "bounced": 120,
    "deferred": 25,
    "failed": 5,
    "opened_total": 8200,
    "opened_unique": 6100,
    "clicked_total": 1500,
    "clicked_unique": 980,
    "unsubscribed": 45,
    "delivery_rate": 98.8,
    "open_rate": 49.4,
    "click_rate": 7.9,
    "bot_opens": 1200,
    "human_opens": 7000,
    "bot_open_pct": 14.6
  }
}

{
  "list": {
    "id": "lst_abc123",
    "name": "Newsletter",
    "description": "Weekly product updates",
    "confirmation_redirect_url": "https://example.com/subscribed",
    "subscriber_count": 0,
    "confirmed_count": 0,
    "created_at": "2026-02-25T12:00:00Z",
    "updated_at": "2026-02-25T12:00:00Z"
  }
}

{
  "subscriber": {
    "id": "sub_xyz789",
    "list_id": "lst_abc123",
    "email": "user@example.com",
    "name": "Jane Doe",
    "status": "pending",
    "consent_page_url": "https://example.com/signup",
    "consent_form_id": "footer-form",
    "consent_timestamp": "2026-02-25T12:00:00Z",
    "validation_result": {
      "status": "valid",
      "action": "accept"
    },
    "created_at": "2026-02-25T12:00:00Z"
  }
}

{
  "id": "camp_7f3a1b2c4d5e",
  "name": "March Newsletter",
  "subject": "What is new this month",
  "from_email": "news@yourdomain.com",
  "status": "draft",
  "contact_list_id": "cl_abc123",
  "created_at": "2026-03-12T14:00:00Z"
}

{
  "campaign_id": "camp_7f3a1b2c4d5e",
  "variants": [
    {
      "variant_id": "var_001",
      "subject": "What is new this month",
      "sent": 5000,
      "opens": 1250,
      "clicks": 380,
      "open_rate": 25.0,
      "click_rate": 7.6,
      "is_winner": false,
      "statistical_significance": 0.82
    },
    {
      "variant_id": "var_002",
      "subject": "You will love what is new this month",
      "sent": 5000,
      "opens": 1650,
      "clicks": 510,
      "open_rate": 33.0,
      "click_rate": 10.2,
      "is_winner": true,
      "statistical_significance": 0.97
    }
  ]
}

{
  "campaign_id": "camp_7f3a1b2c4d5e",
  "sent": 10000,
  "delivered": 9850,
  "opened": 2950,
  "clicked": 890,
  "converted": 142,
  "unsubscribed": 23,
  "bounced": 120,
  "complained": 7
}

{
  "campaign_id": "camp_7f3a1b2c4d5e",
  "confidence_score": 87,
  "factors": [
    {
      "name": "list_hygiene",
      "impact": "positive",
      "recommendation": "Contact list was validated within the last 30 days"
    },
    {
      "name": "sender_reputation",
      "impact": "positive",
      "recommendation": "Domain has strong authentication (DKIM, SPF, DMARC)"
    },
    {
      "name": "content_quality",
      "impact": "neutral",
      "recommendation": "Consider adding a plain text alternative for better deliverability"
    }
  ]
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "validate:read send:write"
}

{}

{
  "active": true,
  "scope": "validate:read send:write",
  "client_id": "your-client-id",
  "username": "42",
  "token_type": "Bearer",
  "exp": 1742486400,
  "iat": 1742482800,
  "account_id": 5
}

{
  "active": false
}

{
  "issuer": "https://api.mailodds.com",
  "authorization_endpoint": "https://api.mailodds.com/oauth/authorize",
  "token_endpoint": "https://api.mailodds.com/oauth/token",
  "revocation_endpoint": "https://api.mailodds.com/oauth/revoke",
  "introspection_endpoint": "https://api.mailodds.com/oauth/introspect",
  "jwks_uri": "https://api.mailodds.com/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic",
    "none"
  ],
  "code_challenge_methods_supported": ["S256"]
}

{
  "store": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "account_id": 5,
    "platform": "woocommerce",
    "store_name": "My Shop",
    "store_url": "https://myshop.com",
    "status": "active",
    "auth_method": "api_key",
    "product_count": 0,
    "last_synced_at": null,
    "last_error": null,
    "sync_interval_seconds": 3600,
    "settings": {},
    "created_at": "2026-03-13T12:00:00Z",
    "updated_at": "2026-03-13T12:00:00Z"
  }
}

{
  "stores": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "platform": "woocommerce",
      "store_name": "My Shop",
      "store_url": "https://myshop.com",
      "status": "active",
      "product_count": 142,
      "last_synced_at": "2026-03-13T11:00:00Z",
      ...
    }
  ]
}

{
  "scheduled": true,
  "store_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "products": [
    {
      "id": "prod_abc123",
      "store_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_id": "456",
      "sku": "WIDGET-001",
      "title": "Premium Widget",
      "description": "A high-quality widget for all your needs.",
      "price_current": 29.99,
      "price_original": 39.99,
      "currency": "USD",
      "sale_start": "2026-03-01T00:00:00Z",
      "sale_end": "2026-03-31T23:59:59Z",
      "stock_status": "instock",
      "stock_quantity": 150,
      "image_url": "https://myshop.com/images/widget.jpg",
      "categories": ["Electronics", "Gadgets"],
      "tags": ["sale", "featured"],
      "product_url": "https://myshop.com/products/premium-widget",
      "is_active": true,
      "created_at": "2026-03-10T08:00:00Z",
      "updated_at": "2026-03-13T11:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 10
}

{
  "score": 85,
  "factors": [
    { "name": "bounce_rate", "value": 0.8, "weight": 0.3 },
    { "name": "complaint_rate", "value": 0.02, "weight": 0.25 },
    { "name": "authentication", "value": 1.0, "weight": 0.2 },
    { "name": "list_quality", "value": 0.92, "weight": 0.15 },
    { "name": "engagement", "value": 0.68, "weight": 0.1 }
  ],
  "recommendation": "Your sender health is excellent. Continue monitoring bounce rates after large sends."
}

{
  "id": "ba_abc123",
  "status": "completed",
  "period_days": 30,
  "total_sent": 48500,
  "hard_bounces": 312,
  "soft_bounces": 89,
  "hard_bounce_rate": 0.64,
  "soft_bounce_rate": 0.18,
  "top_domains": [
    { "domain": "old-isp.example.com", "bounces": 48, "type": "hard" },
    { "domain": "corp-mail.example.net", "bounces": 31, "type": "hard" }
  ],
  "recommendation": "Remove 312 hard-bounced addresses from your lists to protect sender reputation.",
  "created_at": "2026-03-12T14:00:00Z",
  "completed_at": "2026-03-12T14:02:15Z"
}

{
  "items": [
    {
      "email": "user@old-isp.example.com",
      "bounce_type": "hard",
      "diagnostic": "550 5.1.1 User unknown",
      "bounced_at": "2026-03-10T08:12:00Z"
    },
    {
      "email": "admin@corp-mail.example.net",
      "bounce_type": "hard",
      "diagnostic": "550 5.1.1 Mailbox not found",
      "bounced_at": "2026-03-09T15:44:00Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 401
}