Email::Valid(3pm)

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

NAME

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

SYNOPSIS

9         use Email::Valid;
10         print (Email::Valid->address('maurice@hevanet.com') ? 'yes' : 'no');
11

DESCRIPTION

13       This module determines whether an email address is well-formed, and
14       optionally, whether a mail host exists for the domain.
15
16       Please note that there is no way to determine whether an address is
17       deliverable without attempting delivery (for details, see perlfaq 9).
18

PREREQUISITES

20       This module requires perl 5.004 or later and the Mail::Address module.
21       Either the Net::DNS module or the nslookup utility is required for DNS
22       checks.  The Net::Domain::TLD module is required to check the validity
23       of top level domains.
24

METHODS

26         Every method which accepts an <ADDRESS> parameter may
27         be passed either a string or an instance of the Mail::Address
28         class.  All errors raise an exception.
29
30       new ( [PARAMS] )
31           This method is used to construct an Email::Valid object.  It
32           accepts an optional list of named parameters to control the
33           behavior of the object at instantiation.
34
35           The following named parameters are allowed.  See the individual
36           methods below of details.
37
38            -mxcheck
39            -tldcheck
40            -fudge
41            -fqdn
42            -local_rules
43
44       mx ( <ADDRESS>|<DOMAIN> )
45           This method accepts an email address or domain name and determines
46           whether a DNS record (A or MX) exists for it.
47
48           The method returns true if a record is found and undef if not.
49
50           Either the Net::DNS module or the nslookup utility is required for
51           DNS checks.  Using Net::DNS is the preferred method since error
52           handling is improved.  If Net::DNS is available, you can modify the
53           behavior of the resolver (e.g. change the default tcp_timeout
54           value) by manipulating the global Net::DNS::Resolver instance
55           stored in $Email::Valid::Resolver.
56
57       tld ( <ADDRESS> )
58           This method determines whether the domain part of an address is in
59           a recognized top-level domain.
60
61       rfc822 ( <ADDRESS> )
62           This method determines whether an address conforms to the RFC822
63           specification (except for nested comments).  It returns true if it
64           conforms and undef if not.
65
66       fudge ( <TRUE>|<FALSE> )
67           Specifies whether calls to address() should attempt to correct
68           common addressing errors.  Currently, this results in the removal
69           of spaces in AOL addresses, and the conversion of commas to periods
70           in Compuserve addresses.  The default is false.
71
72       fqdn ( <TRUE>|<FALSE> )
73           Species whether addresses passed to address() must contain a fully
74           qualified domain name (FQDN).  The default is true.
75
76       local_rules ( <TRUE>|<FALSE> )
77           Specifies whether addresses passed to address() should be tested
78           for domain specific restrictions.  Currently, this is limited to
79           certain AOL restrictions that I'm aware of.  The default is false.
80
81       mxcheck ( <TRUE>|<FALSE> )
82           Specifies whether addresses passed to address() should be checked
83           for a valid DNS entry.  The default is false.
84
85       tldcheck ( <TRUE>|<FALSE> )
86           Specifies whether addresses passed to address() should be checked
87           for a valid top level domains.  The default is false.
88
89       address ( <ADDRESS> )
90           This is the primary method which determines whether an email
91           address is valid.  It's behavior is modified by the values of
92           mxcheck(), tldcheck(), local_rules(), fqdn(), and fudge().  If the
93           address passes all checks, the (possibly modified) address is
94           returned as a string.  Otherwise, the undefined value is returned.
95           In a list context, the method also returns an instance of the
96           Mail::Address class representing the email address.
97
98       details ()
99           If the last call to address() returned undef, you can call this
100           method to determine why it failed.  Possible values are:
101
102            rfc822
103            local_rules
104            fqdn
105            mxcheck
106            tldcheck
107
108           If the class is not instantiated, you can get the same information
109           from the global $Email::Valid::Details.
110

EXAMPLES

112       Let's see if the address 'maurice@hevanet.com' conforms to the RFC822
113       specification:
114
115         print (Email::Valid->address('maurice@hevanet.com') ? 'yes' : 'no');
116
117       Additionally, let's make sure there's a mail host for it:
118
119         print (Email::Valid->address( -address => 'maurice@hevanet.com',
120                                       -mxcheck => 1 ) ? 'yes' : 'no');
121
122       Let's see an example of how the address may be modified:
123
124         $addr = Email::Valid->address('Alfred Neuman <Neuman @ foo.bar>');
125         print "$addr\n"; # prints Neuman@foo.bar
126
127       Now let's add the check for top level domains:
128
129         $addr = Email::Valid->address( -address => 'Neuman@foo.bar',
130                                        -tldcheck => 1 );
131         print "$addr\n"; # doesn't print anything
132
133       Need to determine why an address failed?
134
135         unless(Email::Valid->address('maurice@hevanet')) {
136           print "address failed $Email::Valid::Details check.\n";
137         }
138
139       If an error is encountered, an exception is raised.  This is really
140       only possible when performing DNS queries.  Trap any exceptions by
141       wrapping the call in an eval block:
142
143         eval {
144           $addr = Email::Valid->address( -address => 'maurice@hevanet.com',
145                                          -mxcheck => 1 );
146         };
147         warn "an error was encountered: $@" if $@;
148

BUGS

150       Email::Valid should work with Perl for Win32.  In my experience,
151       however, Net::DNS queries seem to take an extremely long time when a
152       record cannot be found.
153

AUTHOR

155       Copyright 1998-2003, Maurice Aubrey <maurice@hevanet.com>.  All rights
156       reserved.
157
158       This module is free software; you may redistribute it and/or modify it
159       under the same terms as Perl itself.
160

CREDITS

162       Significant portions of this module are based on the ckaddr program
163       written by Tom Christiansen and the RFC822 address pattern developed by
164       Jeffrey Friedl.  Neither were involved in the construction of this
165       module; all errors are mine.
166
167       Thanks very much to the following people for their suggestions and bug
168       fixes:
169
170         Otis Gospodnetic <otis@DOMINIS.com>
171         Kim Ryan <kimaryan@ozemail.com.au>
172         Pete Ehlke <pde@listserv.music.sony.com>
173         Lupe Christoph
174         David Birnbaum
175         Achim
176         Elizabeth Mattijsen (liz@dijkmat.nl)
177