Client for the BillionVerify email verification API.
client = BillionVerify.new(api_key: System.fetch_env!("BILLIONVERIFY_API_KEY"))
{:ok, result} = BillionVerify.verify(client, "user@example.com")
result["status"]
#=> "valid"Every operation returns {:ok, data} or {:error, %BillionVerify.Error{}}, and has
a ! twin that returns data or raises the error. data is the decoded data
field of the API response: a map with string keys, so fields the API adds later
are never lost.
Options
new/1 takes:
:api_key- required:base_url- default"https://api.billionverify.com"; a trailing/or/v1is dropped:timeout- per-request timeout in milliseconds, default30_000:retries- total attempts for a request that gets 429, 500, 502 or 503, default3:sleep- a one-argument function that waits that many milliseconds between attempts, defaultProcess.sleep/1:req_options- extra options merged into everyReqrequest (for exampleplug: {Req.Test, MyStub}in tests)
Every operation also accepts timeout: ms to override the client timeout for that call.
Summary
Functions
Checks whether the address uses a disposable domain, free of charge (POST /v1/verify/disposable).
Same as check_disposable/3, but returns the data or raises BillionVerify.Error.
Same as check_disposable/3, with the address in the query string (GET /v1/verify/disposable).
Same as check_disposable_via_query/3, but returns the data or raises BillionVerify.Error.
Starts a domain search (POST /v1/domain/search): finds the emails published on a
company's site. max_emails (1 to 200) caps the bill (5 credits per returned email).
Same as create_domain_search/4, but returns the data or raises BillionVerify.Error.
Starts a batch domain search from a CSV of domains (POST /v1/domain/search/batch).
Same as create_domain_search_batch/3, but returns the data or raises BillionVerify.Error.
Creates a webhook (POST /v1/webhooks). url must be HTTPS; events are
"file.completed" and "file.failed". The returned "secret" is shown only once.
Same as create_webhook/4, but returns the data or raises BillionVerify.Error.
Deletes a webhook (DELETE /v1/webhooks/{webhook_id}).
Same as delete_webhook/3, but returns the data or raises BillionVerify.Error.
Downloads a finished batch's results as CSV (GET /v1/domain/search/batch/{batch_id}/results).
Until the batch has finished the API answers 409, returned as an :api error with
status: 409. output_path: "file.csv" writes the CSV there and returns the path.
Same as download_domain_search_batch_results/3, but returns the data or raises BillionVerify.Error.
Downloads a finished job's results as CSV (GET /v1/verify/file/{job_id}/results).
Same as download_file_results/3, but returns the data or raises BillionVerify.Error.
Gets the credit balance (GET /v1/credits).
Same as get_credits/2, but returns the data or raises BillionVerify.Error.
Gets a domain search's status and, once finished, its result (GET /v1/domain/search/{search_id}).
Same as get_domain_search/3, but returns the data or raises BillionVerify.Error.
Gets a batch domain search's status and progress (GET /v1/domain/search/batch/{batch_id}).
Same as get_domain_search_batch/3, but returns the data or raises BillionVerify.Error.
Gets a file job's status and progress (GET /v1/verify/file/{job_id}).
Same as get_file_job_status/3, but returns the data or raises BillionVerify.Error.
Checks the API's health (GET /health, no authentication). Returns %{"status" => "ok", "time" => ...}.
Same as health_check/2, but returns the data or raises BillionVerify.Error.
Lists batch domain searches (GET /v1/domain/search/batch). Options: :limit
(up to 100), :status, :cursor. The result has "items", "has_more" and "next_cursor".
Same as list_domain_search_batches/2, but returns the data or raises BillionVerify.Error.
Lists webhooks (GET /v1/webhooks). Returns the list; the secret is not included.
Same as list_webhooks/2, but returns the data or raises BillionVerify.Error.
Builds a client.
Resumes a paused file job (POST /v1/jobs/{job_id}/resume). Returns the job status.
Same as resume_job/3, but returns the data or raises BillionVerify.Error.
Uploads a CSV, XLSX or TXT file for asynchronous verification (POST /v1/verify/file).
Same as upload_file/3, but returns the data or raises BillionVerify.Error.
Verifies one email address (POST /v1/verify/single).
Same as verify/3, but returns the data or raises BillionVerify.Error.
Verifies up to 50 addresses in one request (POST /v1/verify/bulk).
Same as verify_batch/3, but returns the data or raises BillionVerify.Error.
Verifies a webhook delivery.
The SDK version.
Polls a domain search until completed, completed_with_warning or failed.
Options: :poll_interval (ms, default 5_000), :max_wait (ms, default 600_000).
Same as wait_for_domain_search/3, but returns the data or raises BillionVerify.Error.
Polls a file job until it reaches a final state (completed, completed_with_warning,
failed or cancelled) or stops on paused, and returns its status.
Same as wait_for_file_job/3, but returns the data or raises BillionVerify.Error.
Types
@type result(data) :: {:ok, data} | {:error, BillionVerify.Error.t()}
@type t() :: %BillionVerify{ api_key: String.t(), base_url: String.t(), req_options: keyword(), retries: pos_integer(), sleep: (non_neg_integer() -> any()), timeout: pos_integer() }
Functions
Checks whether the address uses a disposable domain, free of charge (POST /v1/verify/disposable).
Same as check_disposable/3, but returns the data or raises BillionVerify.Error.
Same as check_disposable/3, with the address in the query string (GET /v1/verify/disposable).
Same as check_disposable_via_query/3, but returns the data or raises BillionVerify.Error.
Starts a domain search (POST /v1/domain/search): finds the emails published on a
company's site. max_emails (1 to 200) caps the bill (5 credits per returned email).
Options: :include_role_based (boolean), :max_pages (positive integer).
Same as create_domain_search/4, but returns the data or raises BillionVerify.Error.
Starts a batch domain search from a CSV of domains (POST /v1/domain/search/batch).
file is as in upload_file/3. Options: :max_emails (1 to 200), :include_role_based,
:max_pages, and :column_map (a map such as %{"domain" => "Company Website"}, or
a JSON string).
Same as create_domain_search_batch/3, but returns the data or raises BillionVerify.Error.
Creates a webhook (POST /v1/webhooks). url must be HTTPS; events are
"file.completed" and "file.failed". The returned "secret" is shown only once.
Same as create_webhook/4, but returns the data or raises BillionVerify.Error.
Deletes a webhook (DELETE /v1/webhooks/{webhook_id}).
Same as delete_webhook/3, but returns the data or raises BillionVerify.Error.
Downloads a finished batch's results as CSV (GET /v1/domain/search/batch/{batch_id}/results).
Until the batch has finished the API answers 409, returned as an :api error with
status: 409. output_path: "file.csv" writes the CSV there and returns the path.
Same as download_domain_search_batch_results/3, but returns the data or raises BillionVerify.Error.
Downloads a finished job's results as CSV (GET /v1/verify/file/{job_id}/results).
Filters (:valid, :invalid, :catchall, :role, :unknown, :disposable,
:risky) keep only the matching rows; several filters combine with OR. Without
filters the API redirects to the full result file, which is fetched without the
API key.
Returns the CSV as a binary, or with output_path: "results.csv" writes it there
and returns the path.
Same as download_file_results/3, but returns the data or raises BillionVerify.Error.
Gets the credit balance (GET /v1/credits).
Same as get_credits/2, but returns the data or raises BillionVerify.Error.
Gets a domain search's status and, once finished, its result (GET /v1/domain/search/{search_id}).
Same as get_domain_search/3, but returns the data or raises BillionVerify.Error.
Gets a batch domain search's status and progress (GET /v1/domain/search/batch/{batch_id}).
Same as get_domain_search_batch/3, but returns the data or raises BillionVerify.Error.
Gets a file job's status and progress (GET /v1/verify/file/{job_id}).
:timeout_seconds (0 to 300) turns the call into a long poll: the server answers
when the job finishes or the time is up. The HTTP timeout is extended to match.
Same as get_file_job_status/3, but returns the data or raises BillionVerify.Error.
Checks the API's health (GET /health, no authentication). Returns %{"status" => "ok", "time" => ...}.
Same as health_check/2, but returns the data or raises BillionVerify.Error.
Lists batch domain searches (GET /v1/domain/search/batch). Options: :limit
(up to 100), :status, :cursor. The result has "items", "has_more" and "next_cursor".
Same as list_domain_search_batches/2, but returns the data or raises BillionVerify.Error.
Lists webhooks (GET /v1/webhooks). Returns the list; the secret is not included.
Same as list_webhooks/2, but returns the data or raises BillionVerify.Error.
Builds a client.
Raises a BillionVerify.Error of type :authentication when the API key is empty.
Resumes a paused file job (POST /v1/jobs/{job_id}/resume). Returns the job status.
Same as resume_job/3, but returns the data or raises BillionVerify.Error.
Uploads a CSV, XLSX or TXT file for asynchronous verification (POST /v1/verify/file).
file is {:path, "emails.csv"} or {:data, binary, "emails.csv"}. Options:
:check_smtp, :email_column, :preserve_original.
Same as upload_file/3, but returns the data or raises BillionVerify.Error.
Verifies one email address (POST /v1/verify/single).
Options: :check_smtp, :force_refresh, :include_domain_reputation (booleans,
sent only when given).
Same as verify/3, but returns the data or raises BillionVerify.Error.
Verifies up to 50 addresses in one request (POST /v1/verify/bulk).
More than 50 addresses is rejected locally with a :validation error; use
upload_file/3 for larger lists. Options are those of verify/3.
Same as verify_batch/3, but returns the data or raises BillionVerify.Error.
@spec verify_webhook_signature( binary(), String.t(), String.t(), String.t(), keyword() ) :: boolean()
Verifies a webhook delivery.
Pass the raw request body exactly as received, the X-Webhook-Signature header
("sha256=<hex>"), the X-Webhook-Timestamp header and your webhook secret. The
signed text is "<timestamp>.<raw_body>". Returns false (never raises) for an empty
secret, a timestamp that is not a plain Unix-seconds integer, a wrong signature
or a timestamp more than :tolerance seconds from now (default 300; 0 turns
the time check off). :now (Unix seconds) is for tests.
@spec version() :: String.t()
The SDK version.
Polls a domain search until completed, completed_with_warning or failed.
Options: :poll_interval (ms, default 5_000), :max_wait (ms, default 600_000).
Same as wait_for_domain_search/3, but returns the data or raises BillionVerify.Error.
Polls a file job until it reaches a final state (completed, completed_with_warning,
failed or cancelled) or stops on paused, and returns its status.
Options: :poll_interval (ms, default 5_000), :max_wait (ms, default 600_000).
Returns a :timeout error when the job is still running after :max_wait.
Same as wait_for_file_job/3, but returns the data or raises BillionVerify.Error.