One integration, one question answered: can I send to this address without bouncing? A full check gives a strict yes/no - catch-alls, disposables and unverifiable mailboxes all count as "no", so your bounce rate stays protected. For signup and login forms, fast mode flags bad addresses in well under a second, for free.
Free plan: 100 full verifications every month, with full API access. Free on every plan: fast checks, repeat checks within 24 hours, invalid-syntax answers, /v1/account and test keys.
OpenAPI 3 spec: /v1/openapi.json - import it into Postman, Insomnia or your client generator. Jump to code examples.
Questions, billing, account deletion, privacy requests or a problem with the API or the ChatGPT plugin? Email hello@mailrambo.com or humblepoc@gmail.com. Please include your account email and, for API issues, the endpoint and the error code you received. Never send passwords or full API keys.
See also: Privacy policy · Terms of service · Pricing.
Existing MailRambo customers can check email addresses directly in ChatGPT. The plugin is in review by OpenAI and will appear in the ChatGPT plugin directory once approved.
When ChatGPT first uses MailRambo it opens a MailRambo sign-in page. Sign in with your normal MailRambo account (never in the chat), review the permissions and choose a maximum number of full-check attempts for the connection (0–10; 0 blocks full checks). Then click Approve connection. The connection lasts up to 30 days; disconnect any time in ChatGPT settings.
screen_email - free screening for syntax, likely typos, disposable providers and mail servers. A pass means the mailbox was not checked.verify_email - a full mailbox check using your own credits, only when you ask and confirm, and within your approved limit. Catch-all and unverifiable results are not treated as deliverable.account_balance - your plan and remaining credits.It cannot send email, buy credits or change your plan, and results never prove identity or consent.
approved_check_limit_reached - you used the full-check attempts you approved. Disconnect and reconnect MailRambo in ChatGPT to set a new limit.insufficient_credits / subscription_inactive - top up or reactivate on the pricing page.account_connection_required - the connection expired or was revoked; reconnect it.rate_limited - too many requests in a minute; wait and try again.Try the same checks in your browser before you integrate, or share them with teammates. Each tool page shows the matching API call.
Thin, typed clients with automatic retries, retry-safe batches (idempotency keys added for you) and one error type. Both read MAILRAMBO_API_KEY from the environment.
The mode option needs SDK 0.2 or newer (PyPI 0.2.0; npm 0.2.1 is rolling out through npm's review, so npm may still install 0.1.0 for a short while).
npm · Node source · PyPI · Python source
Verify emails inside n8n workflows with the MailRambo community node: Verify Email (Mode Fast for a free pre-filter, or Full with optional full detail), Start Batch, Get Batch and Get Account. In n8n go to Settings → Community Nodes → Install and enter:
Add your key as a MailRambo API credential; mr_test_ keys work for building workflows for free. npm
Keep your key in an environment variable (MAILRAMBO_KEY) and call the API from your server - never from the browser.
Screen email/password signups before creating a user or sending a confirmation email. Our server-only plugin uses mode=fast, with no verification credits charged.
Signup continues if MailRambo times out or returns an API error. Known syntax, typo, disposable-domain and mail-domain failures block signup. The default timeout is 2 seconds, with no automatic retries; keep your existing email-confirmation and abuse-control settings.
The package requires Better Auth 1.7.7 and Node.js 22 or later (tested on 22.23.3 and 26.7.0). Check compatibility before changing an existing app's auth version; do not force a peer-dependency conflict. Covers /sign-up/email only, not OAuth, OTP, magic links or email changes. Fast mode never confirms mailbox existence. Both live and test keys run real fast checks. Keep the key server-side: screening sends the signup address to MailRambo over HTTPS.
Runtime errors - including an invalid or revoked key - fail open, so monitor configuration separately. Missing credentials or invalid options throw at startup. Direct server signup callers must catch Better Auth's APIError; HTTP callers receive MAILRAMBO_EMAIL_REJECTED with status 400.
Complete Better Auth setup guide · npm package · Source and error handling. This is a MailRambo integration, not a built-in or endorsed Better Auth plugin.
Create a key on the API Keys page and send it as a Bearer token. Keys start with mr_live_ (or mr_test_ for test mode) and are shown only once at creation - we store only a hash.
A full check costs 1 credit per address, drawn from the same balance as your dashboard. Every plan - including Free (100 a month) - can use the API. Fast checks, repeats within 24 hours and invalid-syntax answers are free.
Response (200):
For quick tests, GET /v1/verify?email=jane@acme.com returns the same response. Prefer POST in production: query strings end up in proxy and server logs, and email addresses are personal data.
Syntactically invalid input is answered for free - deliverable: false, reason: "invalid_syntax", no credit charged, and credits_remaining is null.
mode=fast) - freeAdd ?mode=fast (or "mode": "fast" in the body) for an instant check that never contacts the mailbox: standards-based syntax, domain typos, MX records, disposable providers and role addresses. It is free and typically answers in well under a second, so you can call it inline on every signup or login form.
Fast mode can prove an address is bad but never that the mailbox exists, so deliverable is false when a check fails (invalid_syntax, possible_typo, disposable, no_mx) and null otherwise. Show suggestion as "Did you mean…?". Run a full check later (e.g. before your first marketing send) for a confirmed yes/no.
Checking the same address again within 24 hours is free and instant: the answer comes from your earlier check, with "cached": true and credits_remaining: null. Results are kept for 7 days (1 day for catch_all, unverifiable and inbox_full, which can change quickly).
?detail=full)Add ?detail=full (or "detail": "full" in the POST body) to get the intelligence behind the answer: lead grade, inbox provider, flags and the domain's DNS authentication. Same price - 1 credit, and also returned on free repeats. Single full checks only: ignored with mode=fast, and not available for batches or test keys.
grade, score, inbox_provider and dns are null if the domain's DNS could not be read; deliverable is unaffected.
Response (202) - one credit per submitted address is charged up front:
If any address is syntactically invalid the whole batch is rejected with 400 invalid_emails and nothing is charged.
Safe retries: send an Idempotency-Key header (any unique string up to 255 chars, e.g. a UUID). Retrying with the same key and body within 24 hours returns the original response (with Idempotent-Replayed: true) instead of starting - and charging - a second batch.
While running, status is "processing" with progress 0–100. When "completed", results holds one verdict per address:
Poll every few seconds; large lists can take a few minutes. Batches also appear on your dashboard History page.
Check your plan and remaining credits before sending work. Free - no credit is charged.
credits_remaining is everything you can spend now: what's left of this period's plan credits plus pack_credits (from credit packs, which never expire). credits_total is the plan's allowance for the period. period_end is when plan credits reset (may be null on the Free plan).
Create a test key (mr_test_...) on the API Keys page to build your integration for free. Test keys never contact mail servers and never use credits; batches complete immediately. The answer is chosen by the part before the @ (any domain works, +tags are ignored):
| Address | deliverable | reason |
|---|---|---|
| deliverable@example.com | true | mailbox_exists |
| role@example.com | true | role_account |
| disposable@ · spamtrap@ · inbox_full@ · mailbox_disabled@ · catch_all@ · unverifiable@ | false | same as the name |
| not_found@ or anything else | false | mailbox_not_found |
Invalid syntax still returns invalid_syntax. mode=fast with a test key runs the real fast checks (they're free anyway). /v1/account shows your real balance.
The closed set of values reason can take. Treat anything with deliverable: false as "do not send". deliverable: null only appears in fast mode: nothing wrong was found, but the mailbox was not checked.
| reason | deliverable | Meaning |
|---|---|---|
| mailbox_exists | true | Mailbox confirmed to accept mail. |
| role_account | true | Deliverable, but a role inbox (info@, sales@). Consider filtering these for cold outreach. |
| invalid_syntax | false | Not a valid email address. Free - never charged. |
| disposable | false | Temporary/throwaway provider. |
| spamtrap | false | Known spam trap - sending damages your sender reputation. |
| inbox_full | false | Mailbox is full and soft-bounces. |
| mailbox_disabled | false | Mailbox disabled by the provider. |
| catch_all | false | The domain accepts every recipient, so this specific mailbox cannot be confirmed. |
| mailbox_not_found | false | Mailbox does not exist - would hard-bounce. |
| unverifiable | false | Could not be confirmed (greylisting, timeouts). Fail-closed. |
| possible_typo | false | mode=fast only: the domain looks like a typo of a popular provider; see suggestion. |
| no_mx | false | mode=fast only: the domain has no mail server. |
| fast_check_passed | null | mode=fast only: no problem found; the mailbox itself was not checked. |
All errors use a flat envelope: {"error": "<code>", "message": "<human readable>", ...}.
| HTTP | error | When |
|---|---|---|
| 401 | missing_api_key · invalid_api_key · api_key_revoked | No key, an unknown key, or a revoked key. |
| 402 | insufficient_credits · subscription_inactive | Out of credits or subscription inactive. Includes credits_remaining (and credits_required for batches). |
| 400 | invalid_request · invalid_emails | Malformed request (including an unknown mode or detail value), or a batch containing invalid addresses (lists up to 10 offenders; nothing charged). |
| 403 | plan_not_allowed · not_available_on_rapidapi | Batches are not included in your plan, or the endpoint is not offered through the RapidAPI gateway (single verify only there). |
| 404 | not_found | No batch with this id on your account. |
| 409 | idempotency_in_progress | A request with the same Idempotency-Key is still running - retry shortly. |
| 422 | idempotency_key_reused | The Idempotency-Key was already used with a different body. |
| 429 | rate_limited | Rate limit exceeded - back off and retry. |
| 503 | provider_unavailable · temporarily_unavailable | Verification backend unavailable. Charged credits are refunded automatically - retry safely. |
| Endpoint | Limit (per key) |
|---|---|
| /v1/verify?mode=fast | 600 / minute (10/s) - free, answers in well under a second |
| /v1/verify (full check) | 600 / minute requests; sustained full checks are fair-use at about 5 per second per account |
| /v1/verify/batch | 30 / minute (up to 200 addresses each) |
| /v1/verify/batch/{batch_id} | 600 / minute |
| /v1/account | 300 / minute |
Signup and login forms: a full check talks to the recipient's mail server and usually takes 1–5 seconds. For forms, call mode=fast inline (syntax, typos, MX, disposable, role - free and instant) and run the full check afterwards, or only when the fast check passes. Repeat checks of the same address within 24 hours are free and instant.
Lists: use the batch endpoint - 30 calls a minute is up to 6,000 addresses a minute. On 429, back off and retry; both SDKs do this for you. Need a higher sustained rate? Email hello@mailrambo.com.
• 1 credit per full check, shared with your dashboard balance. Plan credits reset each period; credit-pack credits never expire.
• Free: mode=fast checks, repeat checks of the same address within 24 hours, syntactically invalid addresses, /v1/account, and everything with a test key.
• Batches charge all submitted addresses up front; catch-all and unverifiable results are still verification work and are not refunded.
• Provider outages (503) automatically refund the affected credits.