# email-validation.org
email-validation.org checks email addresses: each answer has one of five statuses (valid, invalid, catch-all, unknown,
disposable), a reason and a recommended action. This connector validates one address at a time inside a flow or an app,
runs lists of addresses as bulk jobs, downloads their results as CSV and reads the account's credit balance and usage.

## Publisher: email-validation.org

## Prerequisites
- An email-validation.org account (https://email-validation.org/signin/?new=1) and an API key.
- Credits: each check of a real address uses credits from the account's balance. The test addresses on
  `sandbox.email-validation.org` (for example `accepted@sandbox.email-validation.org`) are free and contact no mail
  server, also in bulk jobs.

## Supported Operations
### Validate an email address
Checks one address and returns its status, reason and recommended action.

### Get your credit balance
Returns the spendable balance, any debt, credits still being applied, and the credit lots with their expiry dates.

### Get credit usage by day or by key
Credit usage for any window within the last 90 days.

### Create a bulk job
Creates a bulk job from a list of addresses sent as JSON: up to 100,000 addresses, at most 4 MB (larger lists and CSV files: upload them in the dashboard).

### Get a bulk job
Returns the job with its progress and counts.

### Cancel a bulk job
Cancels the job.

### Start a bulk job
Starts a job that is ready.

### Download bulk results (CSV)
Streams the results of a completed job as CSV (UTF-8).

### Get service status
Public status of each component.

## Obtaining Credentials
The connector authenticates with an API key. Sign in at https://email-validation.org, open **Dashboard > API keys** and
create a key with the permissions **Validate addresses** and **Read balance and usage** (both on by default; the
connection test reads the balance), and **Bulk lists** for the bulk actions. Give it a daily credit cap to limit what a flow can spend.
When you create a connection, paste the key alone (without "Bearer") and choose the API host:
`api.email-validation.org`, or `api-eu.email-validation.org` for EU data residency (validated and stored in the EU; the same keys and credits).

## Getting Started
1. Create a connection with your API key and host.
2. Add **Validate an email address** to a flow with `accepted@sandbox.email-validation.org`: the result is `valid`
   and free.
3. Use **Status**, **Reason** and **Action** from the result in a condition, for example to skip addresses whose
   action is `remove`.
4. For a list, use **Create a bulk job** with an array of addresses, then a *Do until* loop around **Get a bulk job**
   until the status is `completed`, `failed`, `cancelled` or `expired`, then **Download bulk results (CSV)**.

Guides and the API reference: https://email-validation.org/docs/

## Known Issues and Limitations
- **Create a bulk job** takes JSON only: up to 100,000 addresses and
  4 MB per job. Upload CSV files and larger lists in the dashboard.
- Set **Retry policy** to None and **Asynchronous pattern** to Off in the settings of **Create a bulk job**: the API
  cannot tell a re-sent create from a new list, so a retry can create (and charge for) the same list twice. If a create
  fails with a 5xx error or a timeout, check the bulk page of the dashboard before running it again.
- A bulk job stays on the host that created it: the other host answers its id with `409`.
- **Download bulk results (CSV)** returns file content: pass it to an action that creates a file, or read it as text
  with `base64ToString(body('Download_bulk_results_(CSV)')?['$content'])`.
- There is no trigger yet. To act when a bulk job finishes, poll **Get a bulk job**, or register a flow's HTTP request
  URL as a webhook endpoint in the dashboard and read the job with **Get a bulk job** when it is called.
- A re-sent **Validate an email address** after a lost answer can use credits again; `unknown` results and errors
  never use credits.

## Deployment Instructions
With Microsoft's `paconn` command line tool, from a folder that holds `apiDefinition.swagger.json`,
`apiProperties.json`, `icon.png` and `settings.json`:

```
paconn login
paconn create --settings settings.json
```

`paconn` asks for the environment. Or in the maker portal: **Custom connectors > New custom connector > Import an
OpenAPI file** with `apiDefinition.swagger.json`; then set the icon and the background colour `#0A1226` on
**General**, and on **Definition** add the policy *Set HTTP header*: name `Authorization`, value `Bearer @connectionParameters('api_key')`,
action *override*, run on *Request*. For the EU host, set **Host** to `api-eu.email-validation.org` on **General**.