# EmailAddress
EmailAddress provides top-level parsing & formatting API to deal with RFC5322-formatted
e-mail addresses.
This library is meant to be very forgiving and deal with invalid / malformed e-mail
addresses in a fashion allowing for a recovery and avoiding common errors that happen
when clients send malformed emails.
The case for having a forgiving library to parse e-mail addresses, is that the e-mail
clients do not stick to the rules or have bugs allowing for invalid e-mail addresses to
be used when sending, receiving or processing e-mails.
This library defines e-mail address as a string, which contains what most people think as
e-mail address, i.e. "jack.black@example.com" and additional information, such as first or
last name of the person: "Jack Black <jack.black@example.com>". When parsing, we support
various formats encountered in the wild:
- jack.black@example.com
- Jack Black <jack.black@example.com>
- "Jack@Black" <jack.black@example.com>
- Jack Black jack.black@example.com
- Jack\n\rBlack\tjack.black@example.com
- jack.black@example.com (Jack Black)
- Jack Black <jack.black@127.0.0.1>
etc.
## Installation
If [available in Hex](https://hex.pm/packages/email_address), the package can be installed
by adding `email_address` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:email_address, "~> 1.0"}
]
end
```
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/email_address](https://hexdocs.pm/email_address).
## Usage
Parsing e-mail addresses:
EmailAddress.parse("jack.black@example.com")
=> %EmailAddress.Address{addr_spec: "jack.black@example.com", display_name: ""}
EmailAddress.parse("Jack Black <jack.black@example.com>")
=> %EmailAddress.Address{addr_spec: "jack.black@example.com", display_name: "Jack Black"}
EmailAddress.parse("Not an e-mail")
=> nil
Formatting e-mail address:
EmailAddress.format(%EmailAddress.Address{addr_spec: "jack.black@example.com", display_name: ""})
=> "jack.black@example.com"
EmailAddress.format(%EmailAddress.Address{addr_spec: "jack.black@example.com", display_name: "Jack Black"})
=> "Jack Black <jack.black@example.com>"
EmailAddress.format(%EmailAddress.Address{addr_spec: "jack.black@example.com", display_name: "Jack <Black's> Email"})
=> "\\"Jack <Black's> Email\\" <jack.black@example.com>"
## Thanks
This code has been made open source thanks to [Keeping.com](https://keeping.com). Please check them out if you need a shared Gmail inbox!
## Copyright and License
Copyright (c) 2024, Hubert Łępicki.
EmailAddress source code is licensed under the [MIT License](LICENSE.md).