SDKs

official, typed clients for the v1 api in four languages each one covers the full public surface — single verification, batch jobs, esp integrations and keyword rules, usage reports — and handles auth, retries, and idempotency for you language package requires node js / typescript @mailfloss/sdk https //www npmjs com/package/@mailfloss/sdk node js 18+ python mailfloss https //pypi org/project/mailfloss/ python 3 9+ ruby mailfloss https //rubygems org/gems/mailfloss ruby 2 6+ go github com/mailfloss/mailfloss go https //github com/mailfloss/mailfloss go go 1 24+ all four are mit licensed and zero dependency (standard library only), retry 429 / 5xx responses honoring retry after , and attach an idempotency key to every post so a retried batch submit never double charges you don't need an sdk — every endpoint is plain http + json, as shown in the quickstart quickstart the sdks just save you the plumbing authentication every client sends your key as authorization bearer \<key> (see authentication authentication ) get your key from the dashboard under settings → api the recommended setup is the mailfloss api key environment variable — each client reads it when constructed with no arguments, which keeps the key out of your source tree export mailfloss api key="mf live your key here" you can also pass the key explicitly (shown per language below) if no key is found, the constructor raises a configuration error rather than failing later on the first request install and verify an email node js / typescript npm install @mailfloss/sdk import { mailfloss } from "@mailfloss/sdk"; // reads mailfloss api key, or pass it new mailfloss({ apikey "mf live " }) const mailfloss = new mailfloss(); const result = await mailfloss verify({ email "jane\@acme com" }); console log(result status); // "passed" | "undeliverable" | "risky" | "unknown" console log(result passed); // true when safe to send console log(result reason); // e g "available" console log(result suggestion); // typo fix, when one is detected python pip install mailfloss from mailfloss import mailfloss \# reads mailfloss api key, or pass it mailfloss(api key="mf live ") client = mailfloss() result = client verify("jane\@acme com") print(result\["status"]) # "passed" | "undeliverable" | "risky" | "unknown" print(result\["passed"]) # true when safe to send print(result\["reason"]) # e g "available" if result get("suggestion") print("did you mean ", result\["suggestion"]) ruby gem install mailfloss require "mailfloss" \# reads mailfloss api key, or pass it mailfloss client new(api key "mf live ") client = mailfloss client new result = client verify(email "jane\@acme com") result\[ status] # "passed" | "undeliverable" | "risky" | "unknown" result\[ passed] # true when safe to send result\[ reason] # e g "available" result\[ suggestion] # typo fix, when one is detected responses are parsed with symbol keys go go get github com/mailfloss/mailfloss go package main import ( &#x9;"context" &#x9;"fmt" &#x9;"log" &#x9;mailfloss "github com/mailfloss/mailfloss go" ) func main() { &#x9;// reads mailfloss api key, or pass it mailfloss new(mailfloss withapikey("mf live ")) &#x9;client, err = mailfloss new() &#x9;if err != nil { &#x9; log fatal(err) &#x9;} &#x9;res, err = client verify check(context background(), mailfloss verifyparams{ &#x9; email "jane\@acme com", &#x9;}) &#x9;if err != nil { &#x9; log fatal(err) &#x9;} &#x9;// status is one of passed, undeliverable, risky, unknown &#x9;fmt printf("%s > %s (%s) passed=%t\n", res email, res status, res reason, res passed) } batch verification submit a job, poll its status, then page through results — the same flow as the quickstart quickstart , one method per step pass an optional webhook url to be notified on completion instead of polling node js / typescript const { id } = await mailfloss batchverify create({ emails \["jane\@acme com", "bob\@example com"], webhook url "https //example com/hooks/mailfloss", // optional; omit to poll }); const { status, progress } = await mailfloss batchverify status(id); const page = await mailfloss batchverify results(id, { per page 100 }); console log(page results); python job = client batch verify create( emails=\["jane\@acme com", "bob\@example com"], webhook url="https //example com/hooks/mailfloss", # optional; omit to poll ) status = client batch verify status(job\["id"]) print(status\["status"], status get("progress")) page = client batch verify results(job\["id"], per page=500) for row in page get("results", \[]) print(row) ruby batch = client batch verify create( emails \["jane\@acme com", "bob\@example com"], webhook url "https //example com/hooks/mailfloss" # optional; omit to poll ) status = client batch verify status(batch\[ id]) puts "#{status\[ status]} #{status\[ progress]}" page = client batch verify results(batch\[ id], per page 100) page\[ results] go job, err = client batchverify create(ctx, mailfloss batchverifycreateparams{ &#x9;emails \[]string{"jane\@acme com", "bob\@example com"}, &#x9;webhookurl "https //example com/hooks/mailfloss", // optional; omit to poll }) status, err = client batchverify status(ctx, job id) fmt printf("job %s %s (% 0f%%)\n", job id, status status, status progress) page, err = client batchverify results(ctx, job id, mailfloss batchverifyresultsparams{ &#x9;perpage 1000, }) for , r = range page results { &#x9;fmt printf("%s > %s (%s)\n", r email, r status, r reason) } errors non 2xx responses surface as a language native error carrying the same fields as the json envelope documented in errors errors — status , code , message , type , and request id branch on the stable code , never on message language error type node js / typescript mailflosserror (config problems mailflossconfigerror ) python mailflosserror (config problems mailflossconfigerror ) ruby mailfloss apierror (config problems mailfloss configurationerror ; both subclass mailfloss error ) go mailfloss error , matched with errors as from mailfloss import mailfloss, mailflosserror try client jobs get("does not exist") except mailflosserror as err print(err status) # 404 print(err code) # stable machine readable code print(err request id) # quote this to support pagination list endpoints return a { data, pagination } envelope pass pagination next cursor back as the cursor parameter to fetch the next page — see pagination pagination for the full model next steps api reference — every endpoint, parameter, and response shape connect an esp — verify first automation across 18 email platforms webhooks — get notified instead of polling