BillionVerify (BillionVerify v1.0.0)

Copy Markdown View Source

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 /v1 is dropped
  • :timeout - per-request timeout in milliseconds, default 30_000
  • :retries - total attempts for a request that gets 429, 500, 502 or 503, default 3
  • :sleep - a one-argument function that waits that many milliseconds between attempts, default Process.sleep/1
  • :req_options - extra options merged into every Req request (for example plug: {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, with the address in the query string (GET /v1/verify/disposable).

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).

Starts a batch domain search from a CSV of domains (POST /v1/domain/search/batch).

Creates a webhook (POST /v1/webhooks). url must be HTTPS; events are "file.completed" and "file.failed". The returned "secret" is shown only once.

Deletes a webhook (DELETE /v1/webhooks/{webhook_id}).

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.

Downloads a finished job's results as CSV (GET /v1/verify/file/{job_id}/results).

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}).

Gets a batch domain search's status and progress (GET /v1/domain/search/batch/{batch_id}).

Gets a file job's status and progress (GET /v1/verify/file/{job_id}).

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".

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).

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).

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).

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.

Types

file()

@type file() :: {:path, Path.t()} | {:data, binary(), filename :: String.t()}

result(data)

@type result(data) :: {:ok, data} | {:error, BillionVerify.Error.t()}

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

check_disposable(client, email, opts \\ [])

@spec check_disposable(t(), String.t(), keyword()) :: result(map())

Checks whether the address uses a disposable domain, free of charge (POST /v1/verify/disposable).

check_disposable!(arg1, arg2, opts \\ [])

Same as check_disposable/3, but returns the data or raises BillionVerify.Error.

check_disposable_via_query(client, email, opts \\ [])

@spec check_disposable_via_query(t(), String.t(), keyword()) :: result(map())

Same as check_disposable/3, with the address in the query string (GET /v1/verify/disposable).

check_disposable_via_query!(arg1, arg2, opts \\ [])

Same as check_disposable_via_query/3, but returns the data or raises BillionVerify.Error.

create_domain_search(client, domain, max_emails, opts \\ [])

@spec create_domain_search(t(), String.t(), pos_integer(), keyword()) :: result(map())

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).

create_domain_search!(arg1, arg2, arg3, opts \\ [])

Same as create_domain_search/4, but returns the data or raises BillionVerify.Error.

create_domain_search_batch(client, file, opts \\ [])

@spec create_domain_search_batch(t(), file(), keyword()) :: result(map())

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).

create_domain_search_batch!(arg1, arg2, opts \\ [])

Same as create_domain_search_batch/3, but returns the data or raises BillionVerify.Error.

create_webhook(client, url, events, opts \\ [])

@spec create_webhook(t(), String.t(), [String.t()], keyword()) :: result(map())

Creates a webhook (POST /v1/webhooks). url must be HTTPS; events are "file.completed" and "file.failed". The returned "secret" is shown only once.

create_webhook!(arg1, arg2, arg3, opts \\ [])

Same as create_webhook/4, but returns the data or raises BillionVerify.Error.

delete_webhook(client, webhook_id, opts \\ [])

@spec delete_webhook(t(), String.t(), keyword()) :: result(map() | nil)

Deletes a webhook (DELETE /v1/webhooks/{webhook_id}).

delete_webhook!(arg1, arg2, opts \\ [])

Same as delete_webhook/3, but returns the data or raises BillionVerify.Error.

download_domain_search_batch_results(client, batch_id, opts \\ [])

@spec download_domain_search_batch_results(t(), String.t(), keyword()) ::
  result(binary())

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.

download_domain_search_batch_results!(arg1, arg2, opts \\ [])

Same as download_domain_search_batch_results/3, but returns the data or raises BillionVerify.Error.

download_file_results(client, job_id, opts \\ [])

@spec download_file_results(t(), String.t(), keyword()) :: result(binary())

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.

download_file_results!(arg1, arg2, opts \\ [])

Same as download_file_results/3, but returns the data or raises BillionVerify.Error.

get_credits(client, opts \\ [])

@spec get_credits(t(), keyword()) :: result(map())

Gets the credit balance (GET /v1/credits).

get_credits!(arg1, opts \\ [])

Same as get_credits/2, but returns the data or raises BillionVerify.Error.

get_domain_search(client, search_id, opts \\ [])

@spec get_domain_search(t(), String.t(), keyword()) :: result(map())

Gets a domain search's status and, once finished, its result (GET /v1/domain/search/{search_id}).

get_domain_search!(arg1, arg2, opts \\ [])

Same as get_domain_search/3, but returns the data or raises BillionVerify.Error.

get_domain_search_batch(client, batch_id, opts \\ [])

@spec get_domain_search_batch(t(), String.t(), keyword()) :: result(map())

Gets a batch domain search's status and progress (GET /v1/domain/search/batch/{batch_id}).

get_domain_search_batch!(arg1, arg2, opts \\ [])

Same as get_domain_search_batch/3, but returns the data or raises BillionVerify.Error.

get_file_job_status(client, job_id, opts \\ [])

@spec get_file_job_status(t(), String.t(), keyword()) :: result(map())

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.

get_file_job_status!(arg1, arg2, opts \\ [])

Same as get_file_job_status/3, but returns the data or raises BillionVerify.Error.

health_check(client, opts \\ [])

@spec health_check(t(), keyword()) :: result(map())

Checks the API's health (GET /health, no authentication). Returns %{"status" => "ok", "time" => ...}.

health_check!(arg1, opts \\ [])

Same as health_check/2, but returns the data or raises BillionVerify.Error.

list_domain_search_batches(client, opts \\ [])

@spec list_domain_search_batches(t(), keyword()) :: result(map())

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".

list_domain_search_batches!(arg1, opts \\ [])

Same as list_domain_search_batches/2, but returns the data or raises BillionVerify.Error.

list_webhooks(client, opts \\ [])

@spec list_webhooks(t(), keyword()) :: result([map()])

Lists webhooks (GET /v1/webhooks). Returns the list; the secret is not included.

list_webhooks!(arg1, opts \\ [])

Same as list_webhooks/2, but returns the data or raises BillionVerify.Error.

new(opts)

@spec new(keyword()) :: t()

Builds a client.

Raises a BillionVerify.Error of type :authentication when the API key is empty.

resume_job(client, job_id, opts \\ [])

@spec resume_job(t(), String.t(), keyword()) :: result(map())

Resumes a paused file job (POST /v1/jobs/{job_id}/resume). Returns the job status.

resume_job!(arg1, arg2, opts \\ [])

Same as resume_job/3, but returns the data or raises BillionVerify.Error.

upload_file(client, file, opts \\ [])

@spec upload_file(t(), file(), keyword()) :: result(map())

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.

upload_file!(arg1, arg2, opts \\ [])

Same as upload_file/3, but returns the data or raises BillionVerify.Error.

verify(client, email, opts \\ [])

@spec verify(t(), String.t(), keyword()) :: result(map())

Verifies one email address (POST /v1/verify/single).

Options: :check_smtp, :force_refresh, :include_domain_reputation (booleans, sent only when given).

verify!(arg1, arg2, opts \\ [])

Same as verify/3, but returns the data or raises BillionVerify.Error.

verify_batch(client, emails, opts \\ [])

@spec verify_batch(t(), [String.t()], keyword()) :: result(map())

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.

verify_batch!(arg1, arg2, opts \\ [])

Same as verify_batch/3, but returns the data or raises BillionVerify.Error.

verify_webhook_signature(raw_body, signature, timestamp, secret, opts \\ [])

@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.

version()

@spec version() :: String.t()

The SDK version.

wait_for_domain_search(client, search_id, opts \\ [])

@spec wait_for_domain_search(t(), String.t(), keyword()) :: result(map())

Polls a domain search until completed, completed_with_warning or failed. Options: :poll_interval (ms, default 5_000), :max_wait (ms, default 600_000).

wait_for_domain_search!(arg1, arg2, opts \\ [])

Same as wait_for_domain_search/3, but returns the data or raises BillionVerify.Error.

wait_for_file_job(client, job_id, opts \\ [])

@spec wait_for_file_job(t(), String.t(), keyword()) :: result(map())

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.

wait_for_file_job!(arg1, arg2, opts \\ [])

Same as wait_for_file_job/3, but returns the data or raises BillionVerify.Error.