.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Email::Valid 3"
.TH Email::Valid 3 "2016-03-28" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Email::Valid \- Check validity of Internet email addresses
.SH "VERSION"
.IX Header "VERSION"
version 1.200
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Email::Valid;
\&  my $address = Email::Valid\->address(\*(Aqmaurice@hevanet.com\*(Aq);
\&  print ($address ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module determines whether an email address is well-formed, and
optionally, whether a mail host exists for the domain.
.PP
Please note that there is no way to determine whether an
address is deliverable without attempting delivery
(for details, see perlfaq 9 <http://perldoc.perl.org/perlfaq9.html#How-do-I-check-a-valid-mail-address>).
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
This module requires perl 5.004 or later and the Mail::Address module.
Either the Net::DNS module or the nslookup utility is required
for \s-1DNS\s0 checks.  The Net::Domain::TLD module is required to check the
validity of top level domains.
.SH "METHODS"
.IX Header "METHODS"
Every method which accepts an \f(CW\*(C`<ADDRESS>\*(C'\fR parameter may
be passed either a string or an instance of the Mail::Address
class.  All errors raise an exception.
.IP "new ( [\s-1PARAMS\s0] )" 4
.IX Item "new ( [PARAMS] )"
This method is used to construct an Email::Valid object.
It accepts an optional list of named parameters to
control the behavior of the object at instantiation.
.Sp
The following named parameters are allowed.  See the
individual methods below for details.
.Sp
.Vb 6
\& \-mxcheck
\& \-tldcheck
\& \-fudge
\& \-fqdn
\& \-allow_ip
\& \-local_rules
.Ve
.IP "mx ( <\s-1ADDRESS\s0>|<\s-1DOMAIN\s0> )" 4
.IX Item "mx ( <ADDRESS>|<DOMAIN> )"
This method accepts an email address or domain name and determines
whether a \s-1DNS\s0 record (A or \s-1MX\s0) exists for it.
.Sp
The method returns true if a record is found and undef if not.
.Sp
Either the Net::DNS module or the nslookup utility is required for
\&\s-1DNS\s0 checks.  Using Net::DNS is the preferred method since error
handling is improved.  If Net::DNS is available, you can modify
the behavior of the resolver (e.g. change the default tcp_timeout
value) by manipulating the global Net::DNS::Resolver instance stored in
\&\f(CW$Email::Valid::Resolver\fR.
.IP "rfc822 ( <\s-1ADDRESS\s0> )" 4
.IX Item "rfc822 ( <ADDRESS> )"
This method determines whether an address conforms to the \s-1RFC822\s0
specification (except for nested comments).  It returns true if it
conforms and undef if not.
.IP "fudge ( <\s-1TRUE\s0>|<\s-1FALSE\s0> )" 4
.IX Item "fudge ( <TRUE>|<FALSE> )"
Specifies whether calls to \fIaddress()\fR should attempt to correct
common addressing errors.  Currently, this results in the removal of
spaces in \s-1AOL\s0 addresses, and the conversion of commas to periods in
Compuserve addresses.  The default is false.
.IP "allow_ip ( <\s-1TRUE\s0>|<\s-1FALSE\s0> )" 4
.IX Item "allow_ip ( <TRUE>|<FALSE> )"
Specifies whether a \*(L"domain literal\*(R" is acceptable as the domain part.  That
means addresses like:  \f(CW\*(C`rjbs@[1.2.3.4]\*(C'\fR
.Sp
The checking for the domain literal is stricter than the \s-1RFC\s0 and looser than
checking for a valid \s-1IP\s0 address, \fIbut this is subject to change\fR.
.Sp
The default is true.
.IP "fqdn ( <\s-1TRUE\s0>|<\s-1FALSE\s0> )" 4
.IX Item "fqdn ( <TRUE>|<FALSE> )"
Specifies whether addresses passed to \fIaddress()\fR must contain a fully
qualified domain name (\s-1FQDN\s0).  The default is true.
.Sp
\&\fBPlease note!\fR  \s-1FQDN\s0 checks only occur for non-domain-literals.  In other
words, if you have set \f(CW\*(C`allow_ip\*(C'\fR and the address ends in a bracketed \s-1IP\s0
address, the \s-1FQDN\s0 check will not occur.
.IP "tld ( <\s-1ADDRESS\s0> )" 4
.IX Item "tld ( <ADDRESS> )"
This method determines whether the domain part of an address is in a
recognized top-level domain.
.Sp
\&\fBPlease note!\fR  \s-1TLD\s0 checks only occur for non-domain-literals.  In other
words, if you have set \f(CW\*(C`allow_ip\*(C'\fR and the address ends in a bracketed \s-1IP\s0
address, the \s-1TLD\s0 check will not occur.
.IP "local_rules ( <\s-1TRUE\s0>|<\s-1FALSE\s0> )" 4
.IX Item "local_rules ( <TRUE>|<FALSE> )"
Specifies whether addresses passed to \fIaddress()\fR should be tested
for domain specific restrictions.  Currently, this is limited to
certain \s-1AOL\s0 restrictions that I'm aware of.  The default is false.
.IP "mxcheck ( <\s-1TRUE\s0>|<\s-1FALSE\s0> )" 4
.IX Item "mxcheck ( <TRUE>|<FALSE> )"
Specifies whether addresses passed to \fIaddress()\fR should be checked
for a valid \s-1DNS\s0 entry.  The default is false.
.IP "tldcheck ( <\s-1TRUE\s0>|<\s-1FALSE\s0> )" 4
.IX Item "tldcheck ( <TRUE>|<FALSE> )"
Specifies whether addresses passed to \fIaddress()\fR should be checked
for a valid top level domains.  The default is false.
.IP "address ( <\s-1ADDRESS\s0> )" 4
.IX Item "address ( <ADDRESS> )"
This is the primary method which determines whether an email
address is valid.  Its behavior is modified by the values of
\&\fImxcheck()\fR, \fItldcheck()\fR, \fIlocal_rules()\fR, \fIfqdn()\fR, and \fIfudge()\fR.  If the address
passes all checks, the (possibly modified) address is returned as
a string.  Otherwise, undef is returned.
In a list context, the method also returns an instance of the
Mail::Address class representing the email address.
.IP "details ()" 4
.IX Item "details ()"
If the last call to \fIaddress()\fR returned undef, you can call this
method to determine why it failed.  Possible values are:
.Sp
.Vb 6
\& rfc822
\& localpart
\& local_rules
\& fqdn
\& mxcheck
\& tldcheck
.Ve
.Sp
If the class is not instantiated, you can get the same information
from the global \f(CW$Email::Valid::Details\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Let's see if the address 'maurice@hevanet.com' conforms to the
\&\s-1RFC822\s0 specification:
.PP
.Vb 1
\&  print (Email::Valid\->address(\*(Aqmaurice@hevanet.com\*(Aq) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq);
.Ve
.PP
Additionally, let's make sure there's a mail host for it:
.PP
.Vb 2
\&  print (Email::Valid\->address( \-address => \*(Aqmaurice@hevanet.com\*(Aq,
\&                                \-mxcheck => 1 ) ? \*(Aqyes\*(Aq : \*(Aqno\*(Aq);
.Ve
.PP
Let's see an example of how the address may be modified:
.PP
.Vb 2
\&  $addr = Email::Valid\->address(\*(AqAlfred Neuman <Neuman @ foo.bar>\*(Aq);
\&  print "$addr\en"; # prints Neuman@foo.bar
.Ve
.PP
Now let's add the check for top level domains:
.PP
.Vb 3
\&  $addr = Email::Valid\->address( \-address => \*(AqNeuman@foo.bar\*(Aq,
\&                                 \-tldcheck => 1 );
\&  print "$addr\en"; # doesn\*(Aqt print anything
.Ve
.PP
Need to determine why an address failed?
.PP
.Vb 3
\&  unless(Email::Valid\->address(\*(Aqmaurice@hevanet\*(Aq)) {
\&    print "address failed $Email::Valid::Details check.\en";
\&  }
.Ve
.PP
If an error is encountered, an exception is raised.  This is really
only possible when performing \s-1DNS\s0 queries.  Trap any exceptions by
wrapping the call in an eval block:
.PP
.Vb 5
\&  eval {
\&    $addr = Email::Valid\->address( \-address => \*(Aqmaurice@hevanet.com\*(Aq,
\&                                   \-mxcheck => 1 );
\&  };
\&  warn "an error was encountered: $@" if $@;
.Ve
.SH "CREDITS"
.IX Header "CREDITS"
Significant portions of this module are based on the ckaddr program
written by Tom Christiansen and the \s-1RFC822\s0 address pattern developed
by Jeffrey Friedl.  Neither were involved in the construction of this
module; all errors are mine.
.PP
Thanks very much to the following people for their suggestions and
bug fixes:
.PP
.Vb 7
\&  Otis Gospodnetic <otis@DOMINIS.com>
\&  Kim Ryan <kimaryan@ozemail.com.au>
\&  Pete Ehlke <pde@listserv.music.sony.com>
\&  Lupe Christoph
\&  David Birnbaum
\&  Achim
\&  Elizabeth Mattijsen (liz@dijkmat.nl)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::Address, Net::DNS, Net::Domain::TLD, perlfaq9 <https://metacpan.org/pod/distribution/perlfaq/lib/perlfaq9.pod>
.PP
\&\s-1RFC822\s0 <https://www.ietf.org/rfc/rfc0822.txt> \-
standard for the format of \s-1ARPA\s0 internet text messages.
Superseded by \s-1RFC2822\s0 <https://www.ietf.org/rfc/rfc2822.txt>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Maurice Aubrey <maurice@hevanet.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Alexandr Ciornii <alexchorny@gmail.com>
.IP "\(bu" 4
Karel Miko <karel.miko@gmail.com>
.IP "\(bu" 4
McA <McA@github.com>
.IP "\(bu" 4
Michael Schout <mschout@gkg.net>
.IP "\(bu" 4
Mohammad S Anwar <mohammad.anwar@yahoo.com>
.IP "\(bu" 4
Neil Bowers <neil@bowers.com>
.IP "\(bu" 4
Ricardo \s-1SIGNES\s0 <rjbs@cpan.org>
.IP "\(bu" 4
Steve Bertrand <steveb@cpan.org>
.IP "\(bu" 4
Svetlana <svetlana.wiczer@gmail.com>
.IP "\(bu" 4
Troy Morehouse <troymore@nbnet.nb.ca>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 1998 by Maurice Aubrey.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.