SMSovoMailGuard
<- Back home

Documentation

Integrate SovoMail Guard using a single API key. Follow these steps for authentication, verification requests, bulk CSV jobs, and Razorpay-backed billing.

1. Authenticate and secure your API key

  1. Sign up, confirm the OTP, and log in to the dashboard.
  2. Generate your personal API key (or rotate if compromised). Store it on the server only.
  3. Send the key with every request via the x-api-key header. Never embed it in client-side code.

2. Single verification API

Endpoint: POST https://api.SovoMail Guard.com/api/verifications

# Request

curl -X POST https://api.SovoMail Guard.com/api/verifications \
  -H "x-api-key: sm_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"ceo@brand.com"}'

# Response

{
  "_id": "ver_123",
  "email": "ceo@brand.com",
  "status": "completed",
  "result": {
    "deliverable": true,
    "confidence": "High",
    "reason": "Mailbox accepted RCPT TO",
    "responseTime": 118
  }
}
  • 201 indicates success; 4xx includes an error field (invalid syntax, quota exceeded, etc.).
  • Each unique address consumes one credit (free if re-verified within 24 hours).
  • Rate limit: 120 requests per minute. Apply exponential backoff on HTTP 429/5xx responses.

3. Bulk CSV verification

  1. Prepare a CSV with a single column named email. Download the sample from the dashboard.
  2. Upload via the UI or call POST /api/verifications/bulk with { "emails": ["a@x.com"] }.
  3. We process up to 1000 emails per payload. The dashboard progress bar reflects chunk uploads.
  4. Poll GET /api/verifications to retrieve the latest statuses while processing continues.
  5. Coming soon: CSV exports and webhook callbacks for end-to-end automation.

4. Billing and Razorpay integration

  1. Hit POST /api/billing/checkout with { "plan": "starter" } (or "growth"). The API responds with { checkoutUrl, subscriptionId }.
  2. Redirect your logged-in user to checkoutUrl. Razorpay handles card/UPI capture; we immediately store subscriptionId on the account.
  3. Webhooks (subscription.activated, subscription.cancelled, payment.failed) call /api/billing/razorpay/webhook and keep plan + quota in sync. Configure the webhook secret in RAZORPAY_WEBHOOK_SECRET.
  4. The dashboard shows { usage } / { quota }. Once quota is hit, the verification API returns HTTP 402 until the cycle resets or you upgrade.
  5. Scale plans still run through sales. Paid customers can reopen Razorpay Checkout anytime via the "Manage billing" button on the dashboard.
SOVOMAILGUARD