An RFC 5322 email address parser.

v 3.\+1.\+0\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8357}{}\doxysection{What?}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8357}
Want to see if something could be an email address? Want to grab the display name or just the address out of a string? Put your regexes down and use this parser!

This library does not validate email addresses -\/ we can\textquotesingle{}t really do that without sending an email. However, it attempts to parse addresses using the (fairly liberal) grammar specified in RFC 5322. You can use this to check if user input looks like an email address.

Note carefully though -\/ this parser supports all features of RFC 5322, which means that {\ttfamily \char`\"{}\+Bob Example\char`\"{} $<$bob@example.\+com$>$} is a valid email address. If you just want to validate the {\ttfamily bob@example.\+com} part, that is RFC 5321, for which you want to use something like node-\/address-\/rfc2821.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8358}{}\doxysection{Why use this?}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8358}
Use this library because you can be sure it really respects the RFC\+:
\begin{DoxyItemize}
\item The functions in the recursive decent parser match up with the productions in the RFC
\item The productions from the RFC are written above each function for easy verification
\item Tests include all of the test cases from the \href{https://github.com/dominicsayers/isemail}{\texttt{ is\+\_\+email}} project, which are extensive
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8359}{}\doxysection{Installation}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8359}
npm install email-\/addresses\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8360}{}\doxysection{Example}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8360}

\begin{DoxyCode}{0}
\DoxyCodeLine{\$ node}
\DoxyCodeLine{> addrs = require("{}email-\/addresses"{})}
\DoxyCodeLine{\{ [Function: parse5322]}
\DoxyCodeLine{  parseOneAddress: [Function: parseOneAddressSimple],}
\DoxyCodeLine{  parseAddressList: [Function: parseAddressListSimple] \}}
\DoxyCodeLine{> addrs.parseOneAddress('"{}Jack Bowman"{} <jack@fogcreek.com>')}
\DoxyCodeLine{\{ parts:}
\DoxyCodeLine{   \{ name: [Object],}
\DoxyCodeLine{     address: [Object],}
\DoxyCodeLine{     local: [Object],}
\DoxyCodeLine{     domain: [Object] \},}
\DoxyCodeLine{  name: 'Jack Bowman',}
\DoxyCodeLine{  address: 'jack@fogcreek.com',}
\DoxyCodeLine{  local: 'jack',}
\DoxyCodeLine{  domain: 'fogcreek.com' \}}
\DoxyCodeLine{> addrs.parseAddressList('jack@fogcreek.com, Bob <bob@example.com>')}
\DoxyCodeLine{[ \{ parts:}
\DoxyCodeLine{     \{ name: null,}
\DoxyCodeLine{       address: [Object],}
\DoxyCodeLine{       local: [Object],}
\DoxyCodeLine{       domain: [Object] \},}
\DoxyCodeLine{    name: null,}
\DoxyCodeLine{    address: 'jack@fogcreek.com',}
\DoxyCodeLine{    local: 'jack',}
\DoxyCodeLine{    domain: 'fogcreek.com' \},}
\DoxyCodeLine{  \{ parts:}
\DoxyCodeLine{     \{ name: [Object],}
\DoxyCodeLine{       address: [Object],}
\DoxyCodeLine{       local: [Object],}
\DoxyCodeLine{       domain: [Object] \},}
\DoxyCodeLine{    name: 'Bob',}
\DoxyCodeLine{    address: 'bob@example.com',}
\DoxyCodeLine{    local: 'bob',}
\DoxyCodeLine{    domain: 'example.com' \} ]}
\DoxyCodeLine{> addrs("{}jack@fogcreek.com"{})}
\DoxyCodeLine{\{ ast:}
\DoxyCodeLine{   \{ name: 'address-\/list',}
\DoxyCodeLine{     tokens: 'jack@fogcreek.com',}
\DoxyCodeLine{     semantic: 'jack@fogcreek.com',}
\DoxyCodeLine{     children: [ [Object] ] \},}
\DoxyCodeLine{  addresses:}
\DoxyCodeLine{   [ \{ node: [Object],}
\DoxyCodeLine{       parts: [Object],}
\DoxyCodeLine{       name: null,}
\DoxyCodeLine{       address: 'jack@fogcreek.com',}
\DoxyCodeLine{       local: 'jack',}
\DoxyCodeLine{       domain: 'fogcreek.com' \} ] \}}
\DoxyCodeLine{> addrs("{}bogus"{})}
\DoxyCodeLine{null }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8361}{}\doxysection{API}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8361}
\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8362}{}\doxysection{$<$tt$>$obj = addrs(opts)$<$/tt$>$}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8362}
Call the module directly as a function to get access to the AST. Returns null for a failed parse (an invalid address).

Options\+:


\begin{DoxyItemize}
\item {\ttfamily string} -\/ An email address to parse. Parses as {\ttfamily address-\/list}, a list of email addresses separated by commas.
\item {\ttfamily object} with the following keys\+:
\begin{DoxyItemize}
\item {\ttfamily input} -\/ An email address to parse. Required.
\item {\ttfamily rfc6532} -\/ Enable rfc6532 support (unicode in email addresses). Default\+: {\ttfamily false}.
\item {\ttfamily partial} -\/ Allow a failed parse to return the AST it managed to produce so far. Default\+: {\ttfamily false}.
\item {\ttfamily simple} -\/ Return just the address or addresses parsed. Default\+: {\ttfamily false}.
\item {\ttfamily strict} -\/ Turn off features of RFC 5322 marked \char`\"{}\+Obsolete\char`\"{}. Default\+: {\ttfamily false}.
\item {\ttfamily reject\+TLD} -\/ Require at least one {\ttfamily .} in domain names. Default\+: {\ttfamily false}.
\item {\ttfamily start\+At} -\/ Start the parser at one of {\ttfamily address-\/list}, {\ttfamily from}, {\ttfamily sender}, {\ttfamily reply-\/to}. Default\+: {\ttfamily address-\/list}.
\end{DoxyItemize}
\end{DoxyItemize}

Returns an object with the following properties\+:


\begin{DoxyItemize}
\item {\ttfamily ast} -\/ the full AST of the parse.
\item {\ttfamily addresses} -\/ array of addresses found. Each has the following properties\+:
\begin{DoxyItemize}
\item {\ttfamily parts} -\/ components of the AST that make up the address.
\item {\ttfamily type} -\/ The type of the node, e.\+g. {\ttfamily mailbox}, {\ttfamily address}, {\ttfamily group}.
\item {\ttfamily name} -\/ The extracted name from the email. e.\+g. parsing {\ttfamily \char`\"{}\+Bob\char`\"{} $<$bob@example.\+com$>$} will give {\ttfamily Bob} for the {\ttfamily name}.
\item {\ttfamily address} -\/ The full email address. e.\+g. parsing the above will give {\ttfamily bob@example.\+com} for the {\ttfamily address}.
\item {\ttfamily local} -\/ The local part. e.\+g. parsing the above will give {\ttfamily bob} for {\ttfamily local}.
\item {\ttfamily domain} -\/ The domain part. e.\+g. parsing the above will give {\ttfamily example.\+com} for {\ttfamily domain}.
\end{DoxyItemize}
\end{DoxyItemize}

Note if {\ttfamily simple} is set, the return will be an array of addresses rather than the object above.

Note that addresses can contain a {\ttfamily group} address, which in contrast to the {\ttfamily address} objects will simply contain two properties\+: a {\ttfamily name} and {\ttfamily addresses} which is an array of the addresses in the group. You can identify groups because they will have a {\ttfamily type} of {\ttfamily group}. A group looks something like this\+: {\ttfamily Managing Partners\+:ben@example.\+com,carol@example.\+com;}\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8363}{}\doxysection{$<$tt$>$obj = addrs.\+parse\+One\+Address(opts)$<$/tt$>$}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8363}
Parse a single email address.

Operates similarly to {\ttfamily addrs(opts)}, with the exception that {\ttfamily rfc6532} and {\ttfamily simple} default to {\ttfamily true}.

Returns a single address object as described above. If you set {\ttfamily simple\+: false} the returned object includes a {\ttfamily node} object that contains the AST for the address.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8364}{}\doxysection{$<$tt$>$obj = addrs.\+parse\+Address\+List(opts)$<$/tt$>$}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8364}
Parse a list of email addresses separated by comma.

Operates similarly to {\ttfamily addrs(opts)}, with the exception that {\ttfamily rfc6532} and {\ttfamily simple} default to {\ttfamily true}.

Returns a list of address objects as described above. If you set {\ttfamily simple\+: false} each address will include a {\ttfamily node} object that containst the AST for the address.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8365}{}\doxysection{$<$tt$>$obj = addrs.\+parse\+From(opts)$<$/tt$>$}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8365}
Parse an email header \char`\"{}\+From\+:\char`\"{} address (specified as mailbox-\/list or address-\/list).

Operates similarly to {\ttfamily addrs(opts)}, with the exception that {\ttfamily rfc6532} and {\ttfamily simple} default to {\ttfamily true}.

Returns a list of address objects as described above. If you set {\ttfamily simple\+: false} each address will include a {\ttfamily node} object that containst the AST for the address.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8366}{}\doxysection{$<$tt$>$obj = addrs.\+parse\+Sender(opts)$<$/tt$>$}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8366}
Parse an email header \char`\"{}\+Sender\+:\char`\"{} address (specified as mailbox or address).

Operates similarly to {\ttfamily addrs(opts)}, with the exception that {\ttfamily rfc6532} and {\ttfamily simple} default to {\ttfamily true}.

Returns a single address object as described above. If you set {\ttfamily simple\+: false} the returned object includes a {\ttfamily node} object that contains the AST for the address.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8367}{}\doxysection{$<$tt$>$obj = addrs.\+parse\+Reply\+To(opts)$<$/tt$>$}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8367}
Parse an email header \char`\"{}\+Reply-\/\+To\+:\char`\"{} address (specified as address-\/list).

Operates identically to {\ttfamily addrs.\+parse\+Address\+List(opts)}.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8368}{}\doxysubsection{Usage}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8368}
If you want to simply check whether an address or address list parses, you\textquotesingle{}ll want to call the following functions and check whether the results are null or not\+: {\ttfamily parse\+One\+Address} for a single address and {\ttfamily parse\+Address\+List} for multiple addresses.

If you want to examine the parsed address, for example to extract a name or address, you have some options. The object returned by {\ttfamily parse\+One\+Address} has four helper values on it\+: {\ttfamily name}, {\ttfamily address}, {\ttfamily local}, and {\ttfamily domain}. See the example above to understand is actually returned. (These are equivalent to {\ttfamily parts.\+name.\+semantic}, {\ttfamily parts.\+address.\+semantic}, etc.) These values try to be smart about collapsing whitespace, quotations, and excluding RFC 5322 comments. If you desire, you can also obtain the raw parsed tokens or semantic tokens for those fields. The {\ttfamily parts} value is an object referencing nodes in the AST generated. Nodes in the AST have two values of interest here, {\ttfamily tokens} and {\ttfamily semantic}.


\begin{DoxyCode}{0}
\DoxyCodeLine{> a = addrs.parseOneAddress('Jack  Bowman  <jack@fogcreek.com >')}
\DoxyCodeLine{> a.parts.name.tokens}
\DoxyCodeLine{'Jack  Bowman  '}
\DoxyCodeLine{> a.name}
\DoxyCodeLine{'Jack Bowman'}
\DoxyCodeLine{> a.parts.name.semantic}
\DoxyCodeLine{'Jack Bowman '}
\DoxyCodeLine{> a.parts.address.tokens}
\DoxyCodeLine{'jack@fogcreek.com '}
\DoxyCodeLine{> a.address}
\DoxyCodeLine{'jack@fogcreek.com'}
\DoxyCodeLine{> a.parts.address.semantic}
\DoxyCodeLine{'jack@fogcreek.com' }

\end{DoxyCode}


If you need to, you can inspect the AST directly. The entire AST is returned when calling the module\textquotesingle{}s function.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8369}{}\doxysubsection{References}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8369}

\begin{DoxyItemize}
\item \href{http://tools.ietf.org/html/rfc5322}{\texttt{ http\+://tools.\+ietf.\+org/html/rfc5322}}
\item \href{https://tools.ietf.org/html/rfc6532}{\texttt{ https\+://tools.\+ietf.\+org/html/rfc6532}}
\item \href{https://tools.ietf.org/html/rfc6854}{\texttt{ https\+://tools.\+ietf.\+org/html/rfc6854}}
\item \href{http://code.google.com/p/isemail/}{\texttt{ http\+://code.\+google.\+com/p/isemail/}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8370}{}\doxysubsection{Props}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8370}
Many thanks to \href{https://github.com/dominicsayers}{\texttt{ Dominic Sayers}} and his documentation and tests for the \href{https://github.com/dominicsayers/isemail}{\texttt{ is\+\_\+email}} function which helped greatly in writing this parser.\hypertarget{md_sfcode_node_modules_email_addresses_README_autotoc_md8371}{}\doxysubsection{License}\label{md_sfcode_node_modules_email_addresses_README_autotoc_md8371}
Licensed under the MIT License. See the LICENSE file. 