Email::Valid(3)

📦
version 1.204.0 · 8 versions
, in opensuse-leap 16.0

✨ Email::Valid 💌 — the Email::Valid(3) page, bestie edition 🎀

okay so picture this: a Perl module, a User Contributed one, sitting right there in section 3 of your manual. That's her. That's the girl. Let's get into it 💅

🌸 NAME 🌸

Email::Valid — literally checks if Internet email addresses are valid. That's the whole job. She's a vibe check for your email strings ✨

🦋 VERSION 🦋

version 1.204 👑

🌈 SYNOPSIS 🌈

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

like, that's it. that's the whole romance 💖

💜 DESCRIPTION 💜

So this module determines whether an email address is well-formed — and optionally, whether a mail host actually exists for the domain. Highkey useful.

But bestie, hear me: there is no way to determine whether an address is deliverable without attempting delivery. None. Zero. Not a thing. (for the deets, go see perlfaq 9 <http://perldoc.perl.org/perlfaq9.html#How-do-I-check-a-valid-mail-address>). Periodt. 💀

🧚 PERL VERSION 🧚

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. Slay, backwards compatibility 🫶

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. That's just how she is 🙈

🍓 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 DNS checks
  • The Net::Domain::TLD module is required to check the validity of top level domains

collect them all like pokémon, bestie 🎀

🔥 METHODS 🔥

okay so real talk before we dive in: every method which accepts an <ADDRESS> parameter may be passed either a string or an instance of the Mail::Address class. And — important — all errors raise an exception. No quiet failing. She will tell you. 😭

🌟 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. main character energy fr fr.

The following named parameters are allowed — see the individual methods below for details:

  • -mxcheck
  • -tldcheck
  • -fudge
  • -fqdn
  • -allow_ip
  • -local_rules

🌟 mx ( <ADDRESS>|<DOMAIN> )

This method accepts an email address or domain name and determines whether a DNS record (A or MX) exists for it. detective work 🔍

The method returns true if a record is found and undef if not.

Either the Net::DNS module or the nslookup utility is required for DNS 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 $Email::Valid::Resolver. iykyk 👑

🌟 rfc822 ( <ADDRESS> )

This method determines whether an address conforms to the RFC822 specification (except for nested comments 🫠). It returns true if it conforms and undef if not.

🌟 fudge ( <TRUE>|<FALSE> )

Specifies whether calls to address() should attempt to correct common addressing errors. Currently, this results in the removal of spaces in AOL addresses, and the conversion of commas to periods in Compuserve addresses. The default is false.

she's fixing your typos, not your life choices 💅

🌟 allow_ip ( <TRUE>|<FALSE> )

Specifies whether a "domain literal" is acceptable as the domain part. That means addresses like: "rjbs@[1.2.3.4]"

The checking for the domain literal is stricter than the RFC and looser than checking for a valid IP address, but this is subject to change. The default is true.

🌟 fqdn ( <TRUE>|<FALSE> )

Specifies whether addresses passed to address() must contain a fully qualified domain name (FQDN). The default is true.

Please note! FQDN checks only occur for non-domain-literals. In other words, if you have set "allow_ip" and the address ends in a bracketed IP address, the FQDN check will not occur. 🙈

🌟 tld ( <ADDRESS> )

This method determines whether the domain part of an address is in a recognized top-level domain. queen of knowing her TLDs 👑

Please note! TLD checks only occur for non-domain-literals. In other words, if you have set "allow_ip" and the address ends in a bracketed IP address, the TLD check will not occur. 🙈

🌟 local_rules ( <TRUE>|<FALSE> )

Specifies whether addresses passed to address() should be tested for domain specific restrictions. Currently, this is limited to certain AOL restrictions that I'm aware of. The default is false.

🌟 mxcheck ( <TRUE>|<FALSE> )

Specifies whether addresses passed to address() should be checked for a valid DNS entry. The default is false.

🌟 tldcheck ( <TRUE>|<FALSE> )

Specifies whether addresses passed to address() should be checked for a valid top level domains. The default is false.

🌟 address ( <ADDRESS> ) — the main event 👑

This is the primary method which determines whether an email address is valid. Its behavior is modified by the values of mxcheck(), tldcheck(), local_rules(), fqdn(), and fudge().

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. iconic behavior tbh 💖

🌟 details ()

If the last call to address() returned undef, you can call this method to determine why it failed. She'll tell you exactly what went wrong, no cap. Possible values are:

  • rfc822
  • localpart
  • local_rules
  • fqdn
  • mxcheck
  • tldcheck

If the class is not instantiated, you can get the same information from the global $Email::Valid::Details. 🫶

🎀 EXAMPLES 🎀

Let's see if the address 'maurice@hevanet.com' conforms to the RFC822 specification:

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

Additionally, let's make sure there's a mail host for it:

print (Email::Valid->address( -address => 'maurice@hevanet.com',
                              -mxcheck => 1 ) ? 'yes' : 'no');

Let's see an example of how the address may be modified:

$addr = Email::Valid->address('Alfred Neuman <Neuman @ foo.bar>');
print "$addr\n"; # prints Neuman@foo.bar

Now let's add the check for top level domains:

$addr = Email::Valid->address( -address => 'Neuman@foo.bar',
                               -tldcheck => 1 );
print "$addr\n"; # doesn't print anything

Need to determine why an address failed?

unless(Email::Valid->address('maurice@hevanet')) {
  print "address failed $Email::Valid::Details check.\n";
}

If an error is encountered, an exception is raised. This is really only possible when performing DNS queries. Trap any exceptions by wrapping the call in an eval block:

eval {
  $addr = Email::Valid->address( -address => 'maurice@hevanet.com',
                                 -mxcheck => 1 );
};
warn "an error was encountered: $@" if $@;

ngl that last one is giving responsible adult and we love her for it 🧚

⭐ CREDITS ⭐

Significant portions of this module are based on the ckaddr program written by Tom Christiansen and the RFC822 address pattern developed by Jeffrey Friedl. Neither were involved in the construction of this module; all errors are mine. (iconic humility 💅)

Thanks very much to the following people for their suggestions and bug fixes:

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)

👑 SEE ALSO 👑

go read the RFCs bestie, they're giving lore 🦋

🌸 AUTHOR 🌸

Maurice Aubrey <maurice@hevanet.com> ✨

💖 CONTRIBUTORS 💖

  1. Alexandr Ciornii <alexchorny@gmail.com>
  2. Arne Johannessen <ajnn@cpan.org>
  3. Dan Book <grinnz@gmail.com>
  4. Gene Hightower <gene@digilicious.com>
  5. James E Keenan <jkeenan@cpan.org>
  6. Karel Miko <karel.miko@gmail.com>
  7. McA <McA@github.com>
  8. Michael Schout <mschout@gkg.net>
  9. Mohammad S Anwar <mohammad.anwar@yahoo.com>
  10. Neil Bowers <neil@bowers.com>
  11. Ricardo Signes <rjbs@semiotic.systems>
  12. Steve Bertrand <steveb@cpan.org>
  13. Svetlana <svetlana.wiczer@gmail.com>
  14. Troy Morehouse <troymore@nbnet.nb.ca>
  15. Yanick Champoux <yanick@babyl.dyndns.org>

the whole group chat showed up to help, we love a collaborative era 🫶🎀

This software is copyright (c) 1998 by Maurice Aubrey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in yes bestie go off 💅

and that's the whole page, babes ✨ — brought to you by perl v5.42.0, dated 2024-03-22, still serving Email::Valid(3) realness. mwah 💋🎀

📦 where this page comes from