# `BillionVerify`
[🔗](https://github.com/BillionVerify/billionverify-elixir/blob/v1.0.0/lib/billionverify.ex#L1)

Client for the [BillionVerify](https://billionverify.com) 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.

# `file`

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

# `result`

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

# `t`

```elixir
@type t() :: %BillionVerify{
  api_key: String.t(),
  base_url: String.t(),
  req_options: keyword(),
  retries: pos_integer(),
  sleep: (non_neg_integer() -&gt; any()),
  timeout: pos_integer()
}
```

# `check_disposable`

```elixir
@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!`

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

# `check_disposable_via_query`

```elixir
@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!`

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

# `create_domain_search`

```elixir
@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!`

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

# `create_domain_search_batch`

```elixir
@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!`

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

# `create_webhook`

```elixir
@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!`

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

# `delete_webhook`

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

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

# `delete_webhook!`

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

# `download_domain_search_batch_results`

```elixir
@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!`

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

# `download_file_results`

```elixir
@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!`

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

# `get_credits`

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

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

# `get_credits!`

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

# `get_domain_search`

```elixir
@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!`

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

# `get_domain_search_batch`

```elixir
@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!`

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

# `get_file_job_status`

```elixir
@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!`

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

# `health_check`

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

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

# `health_check!`

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

# `list_domain_search_batches`

```elixir
@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!`

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

# `list_webhooks`

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

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

# `list_webhooks!`

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

# `new`

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

Builds a client.

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

# `resume_job`

```elixir
@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!`

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

# `upload_file`

```elixir
@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!`

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

# `verify`

```elixir
@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!`

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

# `verify_batch`

```elixir
@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!`

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

# `verify_webhook_signature`

```elixir
@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`

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

The SDK version.

# `wait_for_domain_search`

```elixir
@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!`

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

# `wait_for_file_job`

```elixir
@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!`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
