1Email::Valid(3)       User Contributed Perl Documentation      Email::Valid(3)
2
3
4

NAME

6       Email::Valid - Check validity of Internet email addresses
7

VERSION

9       version 1.202
10

SYNOPSIS

12         use Email::Valid;
13         my $address = Email::Valid->address('maurice@hevanet.com');
14         print ($address ? 'yes' : 'no');
15

DESCRIPTION

17       This module determines whether an email address is well-formed, and
18       optionally, whether a mail host exists for the domain.
19
20       Please note that there is no way to determine whether an address is
21       deliverable without attempting delivery (for details, see perlfaq 9
22       <http://perldoc.perl.org/perlfaq9.html#How-do-I-check-a-valid-mail-
23       address>).
24

PREREQUISITES

26       This module requires perl 5.004 or later and the Mail::Address module.
27       Either the Net::DNS module or the nslookup utility is required for DNS
28       checks.  The Net::Domain::TLD module is required to check the validity
29       of top level domains.
30

METHODS

32       Every method which accepts an "<ADDRESS>" parameter may be passed
33       either a string or an instance of the Mail::Address class.  All errors
34       raise an exception.
35
36       new ( [PARAMS] )
37           This method is used to construct an Email::Valid object.  It
38           accepts an optional list of named parameters to control the
39           behavior of the object at instantiation.
40
41           The following named parameters are allowed.  See the individual
42           methods below for details.
43
44            -mxcheck
45            -tldcheck
46            -fudge
47            -fqdn
48            -allow_ip
49            -local_rules
50
51       mx ( <ADDRESS>|<DOMAIN> )
52           This method accepts an email address or domain name and determines
53           whether a DNS record (A or MX) exists for it.
54
55           The method returns true if a record is found and undef if not.
56
57           Either the Net::DNS module or the nslookup utility is required for
58           DNS checks.  Using Net::DNS is the preferred method since error
59           handling is improved.  If Net::DNS is available, you can modify the
60           behavior of the resolver (e.g. change the default tcp_timeout
61           value) by manipulating the global Net::DNS::Resolver instance
62           stored in $Email::Valid::Resolver.
63
64       rfc822 ( <ADDRESS> )
65           This method determines whether an address conforms to the RFC822
66           specification (except for nested comments).  It returns true if it
67           conforms and undef if not.
68
69       fudge ( <TRUE>|<FALSE> )
70           Specifies whether calls to address() should attempt to correct
71           common addressing errors.  Currently, this results in the removal
72           of spaces in AOL addresses, and the conversion of commas to periods
73           in Compuserve addresses.  The default is false.
74
75       allow_ip ( <TRUE>|<FALSE> )
76           Specifies whether a "domain literal" is acceptable as the domain
77           part.  That means addresses like:  "rjbs@[1.2.3.4]"
78
79           The checking for the domain literal is stricter than the RFC and
80           looser than checking for a valid IP address, but this is subject to
81           change.
82
83           The default is true.
84
85       fqdn ( <TRUE>|<FALSE> )
86           Specifies whether addresses passed to address() must contain a
87           fully qualified domain name (FQDN).  The default is true.
88
89           Please note!  FQDN checks only occur for non-domain-literals.  In
90           other words, if you have set "allow_ip" and the address ends in a
91           bracketed IP address, the FQDN check will not occur.
92
93       tld ( <ADDRESS> )
94           This method determines whether the domain part of an address is in
95           a recognized top-level domain.
96
97           Please note!  TLD checks only occur for non-domain-literals.  In
98           other words, if you have set "allow_ip" and the address ends in a
99           bracketed IP address, the TLD check will not occur.
100
101       local_rules ( <TRUE>|<FALSE> )
102           Specifies whether addresses passed to address() should be tested
103           for domain specific restrictions.  Currently, this is limited to
104           certain AOL restrictions that I'm aware of.  The default is false.
105
106       mxcheck ( <TRUE>|<FALSE> )
107           Specifies whether addresses passed to address() should be checked
108           for a valid DNS entry.  The default is false.
109
110       tldcheck ( <TRUE>|<FALSE> )
111           Specifies whether addresses passed to address() should be checked
112           for a valid top level domains.  The default is false.
113
114       address ( <ADDRESS> )
115           This is the primary method which determines whether an email
116           address is valid.  Its behavior is modified by the values of
117           mxcheck(), tldcheck(), local_rules(), fqdn(), and fudge().  If the
118           address passes all checks, the (possibly modified) address is
119           returned as a string.  Otherwise, undef is returned.  In a list
120           context, the method also returns an instance of the Mail::Address
121           class representing the email address.
122
123       details ()
124           If the last call to address() returned undef, you can call this
125           method to determine why it failed.  Possible values are:
126
127            rfc822
128            localpart
129            local_rules
130            fqdn
131            mxcheck
132            tldcheck
133
134           If the class is not instantiated, you can get the same information
135           from the global $Email::Valid::Details.
136

EXAMPLES

138       Let's see if the address 'maurice@hevanet.com' conforms to the RFC822
139       specification:
140
141         print (Email::Valid->address('maurice@hevanet.com') ? 'yes' : 'no');
142
143       Additionally, let's make sure there's a mail host for it:
144
145         print (Email::Valid->address( -address => 'maurice@hevanet.com',
146                                       -mxcheck => 1 ) ? 'yes' : 'no');
147
148       Let's see an example of how the address may be modified:
149
150         $addr = Email::Valid->address('Alfred Neuman <Neuman @ foo.bar>');
151         print "$addr\n"; # prints Neuman@foo.bar
152
153       Now let's add the check for top level domains:
154
155         $addr = Email::Valid->address( -address => 'Neuman@foo.bar',
156                                        -tldcheck => 1 );
157         print "$addr\n"; # doesn't print anything
158
159       Need to determine why an address failed?
160
161         unless(Email::Valid->address('maurice@hevanet')) {
162           print "address failed $Email::Valid::Details check.\n";
163         }
164
165       If an error is encountered, an exception is raised.  This is really
166       only possible when performing DNS queries.  Trap any exceptions by
167       wrapping the call in an eval block:
168
169         eval {
170           $addr = Email::Valid->address( -address => 'maurice@hevanet.com',
171                                          -mxcheck => 1 );
172         };
173         warn "an error was encountered: $@" if $@;
174

CREDITS

176       Significant portions of this module are based on the ckaddr program
177       written by Tom Christiansen and the RFC822 address pattern developed by
178       Jeffrey Friedl.  Neither were involved in the construction of this
179       module; all errors are mine.
180
181       Thanks very much to the following people for their suggestions and bug
182       fixes:
183
184         Otis Gospodnetic <otis@DOMINIS.com>
185         Kim Ryan <kimaryan@ozemail.com.au>
186         Pete Ehlke <pde@listserv.music.sony.com>
187         Lupe Christoph
188         David Birnbaum
189         Achim
190         Elizabeth Mattijsen (liz@dijkmat.nl)
191

SEE ALSO

193       Mail::Address, Net::DNS, Net::Domain::TLD, perlfaq9
194       <https://metacpan.org/pod/distribution/perlfaq/lib/perlfaq9.pod>
195
196       RFC822 <https://www.ietf.org/rfc/rfc0822.txt> - standard for the format
197       of ARPA internet text messages.  Superseded by RFC2822
198       <https://www.ietf.org/rfc/rfc2822.txt>.
199

AUTHOR

201       Maurice Aubrey <maurice@hevanet.com>
202

CONTRIBUTORS

204       •   Alexandr Ciornii <alexchorny@gmail.com>
205
206       •   Karel Miko <karel.miko@gmail.com>
207
208       •   McA <McA@github.com>
209
210       •   Michael Schout <mschout@gkg.net>
211
212       •   Mohammad S Anwar <mohammad.anwar@yahoo.com>
213
214       •   Neil Bowers <neil@bowers.com>
215
216       •   Ricardo SIGNES <rjbs@cpan.org>
217
218       •   Steve Bertrand <steveb@cpan.org>
219
220       •   Svetlana <svetlana.wiczer@gmail.com>
221
222       •   Troy Morehouse <troymore@nbnet.nb.ca>
223
225       This software is copyright (c) 1998 by Maurice Aubrey.
226
227       This is free software; you can redistribute it and/or modify it under
228       the same terms as the Perl 5 programming language system itself.
229
230
231
232perl v5.34.0                      2021-07-22                   Email::Valid(3)
Impressum