1Email::Valid(3) User Contributed Perl Documentation Email::Valid(3)
2
6 Email::Valid - Check validity of Internet email addresses
7
9 version 1.203
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 library should run on perls released even a long time ago. It
27 should work on any version of perl released in the last five years.
28 Although it may work on older versions of perl, no guarantee is made
30 that the minimum required version will not be increased. The version
31 may be increased for any reason, and there is no promise that patches
32 will be accepted to lower the minimum required perl.
33
35 This module requires perl 5.004 or later and the Mail::Address module.
36 Either the Net::DNS module or the nslookup utility is required for DNS
37 checks. The Net::Domain::TLD module is required to check the validity
38 of top level domains.
39
41 Every method which accepts an "<ADDRESS>" parameter may be passed
42 either a string or an instance of the Mail::Address class. All errors
43 raise an exception.
44 new ( [PARAMS] )
46 This method is used to construct an Email::Valid object. It
47 accepts an optional list of named parameters to control the
48 behavior of the object at instantiation.
49 The following named parameters are allowed. See the individual
51 methods below for details.
52 -mxcheck
54 -tldcheck
55 -fudge
56 -fqdn
57 -allow_ip
58 -local_rules
59 mx ( <ADDRESS>|<DOMAIN> )
61 This method accepts an email address or domain name and determines
62 whether a DNS record (A or MX) exists for it.
63 The method returns true if a record is found and undef if not.
65 Either the Net::DNS module or the nslookup utility is required for
67 DNS checks. Using Net::DNS is the preferred method since error
68 handling is improved. If Net::DNS is available, you can modify the
69 behavior of the resolver (e.g. change the default tcp_timeout
70 value) by manipulating the global Net::DNS::Resolver instance
71 stored in $Email::Valid::Resolver.
72 rfc822 ( <ADDRESS> )
74 This method determines whether an address conforms to the RFC822
75 specification (except for nested comments). It returns true if it
76 conforms and undef if not.
77 fudge ( <TRUE>|<FALSE> )
79 Specifies whether calls to address() should attempt to correct
80 common addressing errors. Currently, this results in the removal
81 of spaces in AOL addresses, and the conversion of commas to periods
82 in Compuserve addresses. The default is false.
83 allow_ip ( <TRUE>|<FALSE> )
85 Specifies whether a "domain literal" is acceptable as the domain
86 part. That means addresses like: "rjbs@[1.2.3.4]"
87 The checking for the domain literal is stricter than the RFC and
89 looser than checking for a valid IP address, but this is subject to
90 change.
91 The default is true.
93 fqdn ( <TRUE>|<FALSE> )
95 Specifies whether addresses passed to address() must contain a
96 fully qualified domain name (FQDN). The default is true.
97 Please note! FQDN checks only occur for non-domain-literals. In
99 other words, if you have set "allow_ip" and the address ends in a
100 bracketed IP address, the FQDN check will not occur.
101 tld ( <ADDRESS> )
103 This method determines whether the domain part of an address is in
104 a recognized top-level domain.
105 Please note! TLD checks only occur for non-domain-literals. In
107 other words, if you have set "allow_ip" and the address ends in a
108 bracketed IP address, the TLD check will not occur.
109 local_rules ( <TRUE>|<FALSE> )
111 Specifies whether addresses passed to address() should be tested
112 for domain specific restrictions. Currently, this is limited to
113 certain AOL restrictions that I'm aware of. The default is false.
114 mxcheck ( <TRUE>|<FALSE> )
116 Specifies whether addresses passed to address() should be checked
117 for a valid DNS entry. The default is false.
118 tldcheck ( <TRUE>|<FALSE> )
120 Specifies whether addresses passed to address() should be checked
121 for a valid top level domains. The default is false.
122 address ( <ADDRESS> )
124 This is the primary method which determines whether an email
125 address is valid. Its behavior is modified by the values of
126 mxcheck(), tldcheck(), local_rules(), fqdn(), and fudge(). If the
127 address passes all checks, the (possibly modified) address is
128 returned as a string. Otherwise, undef is returned. In a list
129 context, the method also returns an instance of the Mail::Address
130 class representing the email address.
131 details ()
133 If the last call to address() returned undef, you can call this
134 method to determine why it failed. Possible values are:
135 rfc822
137 localpart
138 local_rules
139 fqdn
140 mxcheck
141 tldcheck
142 If the class is not instantiated, you can get the same information
144 from the global $Email::Valid::Details.
145
147 Let's see if the address 'maurice@hevanet.com' conforms to the RFC822
148 specification:
149 print (Email::Valid->address('maurice@hevanet.com') ? 'yes' : 'no');
151 Additionally, let's make sure there's a mail host for it:
153 print (Email::Valid->address( -address => 'maurice@hevanet.com',
155 -mxcheck => 1 ) ? 'yes' : 'no');
156 Let's see an example of how the address may be modified:
158 $addr = Email::Valid->address('Alfred Neuman <Neuman @ foo.bar>');
160 print "$addr\n"; # prints Neuman@foo.bar
161 Now let's add the check for top level domains:
163 $addr = Email::Valid->address( -address => 'Neuman@foo.bar',
165 -tldcheck => 1 );
166 print "$addr\n"; # doesn't print anything
167 Need to determine why an address failed?
169 unless(Email::Valid->address('maurice@hevanet')) {
171 print "address failed $Email::Valid::Details check.\n";
172 }
173 If an error is encountered, an exception is raised. This is really
175 only possible when performing DNS queries. Trap any exceptions by
176 wrapping the call in an eval block:
177 eval {
179 $addr = Email::Valid->address( -address => 'maurice@hevanet.com',
180 -mxcheck => 1 );
181 };
182 warn "an error was encountered: $@" if $@;
183
185 Significant portions of this module are based on the ckaddr program
186 written by Tom Christiansen and the RFC822 address pattern developed by
187 Jeffrey Friedl. Neither were involved in the construction of this
188 module; all errors are mine.
189 Thanks very much to the following people for their suggestions and bug
191 fixes:
192 Otis Gospodnetic <otis@DOMINIS.com>
194 Kim Ryan <kimaryan@ozemail.com.au>
195 Pete Ehlke <pde@listserv.music.sony.com>
196 Lupe Christoph
197 David Birnbaum
198 Achim
199 Elizabeth Mattijsen (liz@dijkmat.nl)
200
202 Mail::Address, Net::DNS, Net::Domain::TLD, perlfaq9
203 <https://metacpan.org/pod/distribution/perlfaq/lib/perlfaq9.pod>
204 RFC822 <https://www.ietf.org/rfc/rfc0822.txt> - standard for the format
206 of ARPA internet text messages. Superseded by RFC2822
207 <https://www.ietf.org/rfc/rfc2822.txt>.
208
210 Maurice Aubrey <maurice@hevanet.com>
211
213 • Alexandr Ciornii <alexchorny@gmail.com>
214 • Dan Book <grinnz@gmail.com>
216 • Gene Hightower <gene@digilicious.com>
218 • Karel Miko <karel.miko@gmail.com>
220 • McA <McA@github.com>
222 • Michael Schout <mschout@gkg.net>
224 • Mohammad S Anwar <mohammad.anwar@yahoo.com>
226 • Neil Bowers <neil@bowers.com>
228 • Ricardo Signes <rjbs@cpan.org>
230 • Ricardo Signes <rjbs@semiotic.systems>
232 • Steve Bertrand <steveb@cpan.org>
234 • Svetlana <svetlana.wiczer@gmail.com>
236 • Troy Morehouse <troymore@nbnet.nb.ca>
238 • Yanick Champoux <yanick@babyl.dyndns.org>
240
242 This software is copyright (c) 1998 by Maurice Aubrey.
243 This is free software; you can redistribute it and/or modify it under
245 the same terms as the Perl 5 programming language system itself.
246perl v5.36.0 2023-02-09 Email::Valid(3)