{"openapi":"3.1.0","info":{"title":"MailRambo Verification API","description":"Strict yes/no email deliverability. `deliverable` is true only for confirmed mailboxes; `reason` explains every answer. 1 credit per verified address; invalid syntax is free. Use `mr_test_` keys to integrate without spending credits.","version":"1.0.0"},"servers":[{"url":"https://www.mailrambo.com"}],"paths":{"/v1/account":{"get":{"tags":["public-api"],"summary":"Account","description":"Plan, remaining credits and cycle end for the key's owner (free).","operationId":"account_v1_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1AccountResponse"}}}},"400":{"description":"Invalid request (invalid_request, invalid_emails).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits or subscription inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Verification backend unavailable; charged credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/verify":{"get":{"tags":["public-api"],"summary":"Verify Get","description":"Verify one email address (1 credit; free if syntactically invalid, a repeat within 24h, or mode=fast).","operationId":"verify_get_v1_verify_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string","title":"Email"}},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["full"]},"description":"Set to `full` to include the `detail` block (same 1 credit)."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["fast","full"],"default":"full"},"description":"`fast`: free sub-second check for forms (syntax, typos, MX, disposable, role); `deliverable` is false or null. `full` (default): mailbox check, 1 credit."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1VerifyResponse"}}}},"400":{"description":"Invalid request (invalid_request, invalid_emails).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits or subscription inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Verification backend unavailable; charged credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["public-api"],"summary":"Verify Post","description":"Verify one email address (1 credit; free if syntactically invalid, a repeat within 24h, or mode=fast).","operationId":"verify_post_v1_verify_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["full"]},"description":"Set to `full` to include the `detail` block (same 1 credit)."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["fast","full"],"default":"full"},"description":"`fast`: free sub-second check for forms (syntax, typos, MX, disposable, role); `deliverable` is false or null. `full` (default): mailbox check, 1 credit."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1VerifyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1VerifyResponse"}}}},"400":{"description":"Invalid request (invalid_request, invalid_emails).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits or subscription inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Verification backend unavailable; charged credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verify/batch":{"post":{"tags":["public-api"],"summary":"Verify Batch Create","description":"Start a batch verification (1 credit per address, charged up front).\n\nAn optional Idempotency-Key header makes retries safe: the same key with\nthe same body replays the first response instead of charging again.","operationId":"verify_batch_create_v1_verify_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BatchRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BatchCreateResponse"}}}},"400":{"description":"Invalid request (invalid_request, invalid_emails).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits or subscription inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Verification backend unavailable; charged credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Same Idempotency-Key still in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retry safely: same key + body within 24h replays the first response."}]}},"/v1/verify/batch/{batch_id}":{"get":{"tags":["public-api"],"summary":"Verify Batch Status","description":"Poll a batch. Results (one yes/no per address) appear when completed.","operationId":"verify_batch_status_v1_verify_batch__batch_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","title":"Batch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1BatchStatusResponse"}}}},"400":{"description":"Invalid request (invalid_request, invalid_emails).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits or subscription inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Verification backend unavailable; charged credits are refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No batch with this id on your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"V1AccountResponse":{"properties":{"plan":{"type":"string","title":"Plan"},"plan_name":{"type":"string","title":"Plan Name"},"status":{"type":"string","title":"Status"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"credits_total":{"type":"integer","title":"Credits Total"},"pack_credits":{"type":"integer","title":"Pack Credits","default":0},"period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period End"},"cancel_at_period_end":{"type":"boolean","title":"Cancel At Period End","default":false}},"type":"object","required":["plan","plan_name","status","credits_remaining","credits_total"],"title":"V1AccountResponse"},"V1BatchCreateResponse":{"properties":{"batch_id":{"type":"string","title":"Batch Id"},"emails_submitted":{"type":"integer","title":"Emails Submitted"},"status":{"type":"string","title":"Status"},"credits_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Remaining"}},"type":"object","required":["batch_id","emails_submitted","status"],"title":"V1BatchCreateResponse"},"V1BatchRequest":{"properties":{"emails":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Emails"},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name"}},"type":"object","required":["emails"],"title":"V1BatchRequest"},"V1BatchResultRow":{"properties":{"email":{"type":"string","title":"Email"},"deliverable":{"type":"boolean","title":"Deliverable"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["email","deliverable","reason"],"title":"V1BatchResultRow"},"V1BatchStatusResponse":{"properties":{"batch_id":{"type":"string","title":"Batch Id"},"status":{"type":"string","title":"Status"},"progress":{"type":"number","title":"Progress"},"total":{"type":"integer","title":"Total"},"checked":{"type":"integer","title":"Checked"},"results":{"anyOf":[{"items":{"$ref":"#/components/schemas/V1BatchResultRow"},"type":"array"},{"type":"null"}],"title":"Results"}},"type":"object","required":["batch_id","status","progress","total","checked"],"title":"V1BatchStatusResponse"},"V1VerifyRequest":{"properties":{"email":{"type":"string","maxLength":320,"title":"Email"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mode"}},"type":"object","required":["email"],"title":"V1VerifyRequest"},"V1VerifyResponse":{"properties":{"email":{"type":"string","title":"Email"},"deliverable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true only for confirmed mailboxes. null only in mode=fast when no problem was found."},"reason":{"type":"string","title":"Reason"},"credits_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Remaining"},"detail":{"$ref":"#/components/schemas/V1Detail","description":"Present only when detail=full was requested."},"cached":{"type":"boolean","description":"true when answered free from your own check of this address in the last 24h."},"mode":{"type":"string","enum":["fast"],"description":"Present in mode=fast responses."},"suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"mode=fast: corrected address for common domain typos."},"checks":{"anyOf":[{"type":"object","properties":{"mx":{"type":"boolean"},"disposable":{"type":"boolean"},"role_account":{"type":"boolean"},"free_email":{"type":"boolean"}}},{"type":"null"}],"description":"mode=fast: individual check results."}},"type":"object","required":["email","deliverable","reason"],"title":"V1VerifyResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","example":"insufficient_credits"},"message":{"type":"string"}},"additionalProperties":true},"V1Detail":{"properties":{"grade":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Grade"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Score"},"inbox_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Inbox Provider"},"flags":{"$ref":"#/components/schemas/V1Flags"},"dns":{"anyOf":[{"$ref":"#/components/schemas/V1Dns"},{"type":"null"}],"default":null}},"required":["flags"],"title":"V1Detail","type":"object"},"V1Dns":{"properties":{"mx":{"title":"Mx","type":"boolean"},"mx_hosts":{"items":{"type":"string"},"title":"Mx Hosts","type":"array"},"spf":{"title":"Spf","type":"boolean"},"dmarc_policy":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Dmarc Policy"},"dkim_selectors":{"items":{"type":"string"},"title":"Dkim Selectors","type":"array"},"bimi":{"title":"Bimi","type":"boolean"},"ptr":{"title":"Ptr","type":"boolean"}},"required":["mx","mx_hosts","spf","dkim_selectors","bimi","ptr"],"title":"V1Dns","type":"object"},"V1Flags":{"properties":{"free_email":{"title":"Free Email","type":"boolean"},"role_account":{"title":"Role Account","type":"boolean"},"disposable":{"title":"Disposable","type":"boolean"},"catch_all":{"title":"Catch All","type":"boolean"},"mailbox_exists":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Mailbox Exists"}},"required":["free_email","role_account","disposable","catch_all"],"title":"V1Flags","type":"object"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"},"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"mr_live_... / mr_test_..."}}},"security":[{"ApiKey":[]}]}