# `EctoCommons.EmailValidator`
[🔗](https://github.com/achedeuzot/ecto_commons/blob/v0.3.7/lib/validators/email.ex#L1)

Validates emails.

## Options
There are various `:checks` depending on the strictness of the validation you require. Indeed, perfect email validation
does not exist (see StackOverflow questions about it):

- `:html_input`: Checks if the email follows the regular expression used by browsers for
  their `type="email"` input fields. This is the default as it corresponds to most use-cases. It is quite strict
  without being too narrow. It does not support unicode emails though. If you need better internationalization,
  please use the `:pow` check as it is more flexible with international emails. Defaults to enabled.
- `:burner`: Checks if the email given is a burner email provider (uses the `Burnex` lib under the hood,
  so make sure to add it to your dependencies). When enabled, will reject temporary email providers. Defaults to disabled.
- `:check_mx_record`: Checks if the email domain exists in the DNS system (can be a bit slow).
- `:pow`: Checks the email using the [`pow`](https://hex.pm/packages/pow) logic. Defaults to disabled.
  The rules are the following:
  - Split into local-part and domain at last `@` occurrence
  - Local-part should;
    - be at most 64 octets
    - separate quoted and unquoted content with a single dot
    - only have letters, digits, and the following characters outside quoted
      content:
        ```text
        !#$%&'*+-/=?^_`{|}~.
        ```
    - not have any consecutive dots outside quoted content
  - Domain should;
    - be at most 255 octets
    - only have letters, digits, hyphen, and dots

  Unicode characters are permitted in both local-part and domain.

  The implementation is based on [RFC 3696](https://tools.ietf.org/html/rfc3696#section-3).
  IP addresses are not allowed as per the RFC 3696 specification: "The domain name can also be
  replaced by an IP address in square brackets, but that form is strongly discouraged except
  for testing and troubleshooting purposes.".

  You're invited to compare the tests to see the difference between the `:html_input`
  check and the `:pow` check. `:pow` is better suited for i18n and is more correct
  in regards to the email specification but will allow valid emails many systems don't
  manage correctly. `:html_input` is more basic but should be OK for most common use-cases.

## Example:

    iex> types = %{email: :string}
    iex> params = %{email: "valid.email@example.com"}
    iex> Ecto.Changeset.cast({%{}, types}, params, Map.keys(types))
    ...> |> validate_email(:email)
    #Ecto.Changeset<action: nil, changes: %{email: "valid.email@example.com"}, errors: [], data: %{}, valid?: true, ...>

    iex> types = %{email: :string}
    iex> params = %{email: "@invalid_email"}
    iex> Ecto.Changeset.cast({%{}, types}, params, Map.keys(types))
    ...> |> validate_email(:email)
    #Ecto.Changeset<action: nil, changes: %{email: "@invalid_email"}, errors: [email: {"is not a valid email", [validation: :email]}], data: %{}, valid?: false, ...>

    iex> types = %{email: :string}
    iex> params = %{email: "uses_a_forbidden_provider@yopmail.net"}
    iex> Ecto.Changeset.cast({%{}, types}, params, Map.keys(types))
    ...> |> validate_email(:email, checks: [:html_input, :burner])
    #Ecto.Changeset<action: nil, changes: %{email: "uses_a_forbidden_provider@yopmail.net"}, errors: [email: {"uses a forbidden provider", [validation: :email]}], data: %{}, valid?: false, ...>

    iex> types = %{email: :string}
    iex> params = %{email: "uses_a_forbidden_provider@yopmail.net"}
    iex> Ecto.Changeset.cast({%{}, types}, params, Map.keys(types))
    ...> |> validate_email(:email, checks: [:html_input, :pow])
    #Ecto.Changeset<action: nil, changes: %{email: "uses_a_forbidden_provider@yopmail.net"}, errors: [], data: %{}, valid?: true, ...>

# `validate_email`

---

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