1Email::Valid(3) User Contributed Perl Documentation Email::Valid(3)
2
6 Email::Valid - Check validity of Internet email addresses
7
9 version 1.202
10
12 use Email::Valid;
13 my $address = Email::Valid->address('maurice@hevanet.com');
14 print ($address ? 'yes' : 'no');
15
17 This module determines whether an email address is well-formed, and
18 optionally, whether a mail host exists for the domain.
19 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
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
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 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 The following named parameters are allowed. See the individual
42 methods below for details.
43 -mxcheck
45 -tldcheck
46 -fudge
47 -fqdn
48 -allow_ip
49 -local_rules
50 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 The method returns true if a record is found and undef if not.
56 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 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 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 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 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 The default is true.
84 fqdn ( <TRUE>|<FALSE> )
86 Specifies whether addresses passed to address() must contain a
87 fully qualified domain name (FQDN). The default is true.
88 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 tld ( <ADDRESS> )
94 This method determines whether the domain part of an address is in
95 a recognized top-level domain.
96 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 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 mxcheck ( <TRUE>|<FALSE> )
107 Specifies whether addresses passed to address() should be checked
108 for a valid DNS entry. The default is false.
109 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 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 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 rfc822
128 localpart
129 local_rules
130 fqdn
131 mxcheck
132 tldcheck
133 If the class is not instantiated, you can get the same information
135 from the global $Email::Valid::Details.
136
138 Let's see if the address 'maurice@hevanet.com' conforms to the RFC822
139 specification:
140 print (Email::Valid->address('maurice@hevanet.com') ? 'yes' : 'no');
142 Additionally, let's make sure there's a mail host for it:
144 print (Email::Valid->address( -address => 'maurice@hevanet.com',
146 -mxcheck => 1 ) ? 'yes' : 'no');
147 Let's see an example of how the address may be modified:
149 $addr = Email::Valid->address('Alfred Neuman <Neuman @ foo.bar>');
151 print "$addr\n"; # prints Neuman@foo.bar
152 Now let's add the check for top level domains:
154 $addr = Email::Valid->address( -address => 'Neuman@foo.bar',
156 -tldcheck => 1 );
157 print "$addr\n"; # doesn't print anything
158 Need to determine why an address failed?
160 unless(Email::Valid->address('maurice@hevanet')) {
162 print "address failed $Email::Valid::Details check.\n";
163 }
164 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 eval {
170 $addr = Email::Valid->address( -address => 'maurice@hevanet.com',
171 -mxcheck => 1 );
172 };
173 warn "an error was encountered: $@" if $@;
174
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 Thanks very much to the following people for their suggestions and bug
182 fixes:
183 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
193 Mail::Address, Net::DNS, Net::Domain::TLD, perlfaq9
194 <https://metacpan.org/pod/distribution/perlfaq/lib/perlfaq9.pod>
195 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
201 Maurice Aubrey <maurice@hevanet.com>
202
204 • Alexandr Ciornii <alexchorny@gmail.com>
205 • Karel Miko <karel.miko@gmail.com>
207 • McA <McA@github.com>
209 • Michael Schout <mschout@gkg.net>
211 • Mohammad S Anwar <mohammad.anwar@yahoo.com>
213 • Neil Bowers <neil@bowers.com>
215 • Ricardo SIGNES <rjbs@cpan.org>
217 • Steve Bertrand <steveb@cpan.org>
219 • Svetlana <svetlana.wiczer@gmail.com>
221 • Troy Morehouse <troymore@nbnet.nb.ca>
223
225 This software is copyright (c) 1998 by Maurice Aubrey.
226 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.
229perl v5.32.1 2021-01-27 Email::Valid(3)