CheckUser(3pm)

💖 NAME 💖

Mail::CheckUser — bestie, this lil Perl module checks email addresses for validity. Yes, fr. It lives in the 3pm section (user contributed Perl docs, iconic) 💅

---

✨ SYNOPSIS ✨

Okay so first up, the chill way — just import the one function:

use Mail::CheckUser qw(check_email);
my $ok = check_email($email_addr);

Or, if you want the constants AND the receipts from your last check:

use Mail::CheckUser qw(:constants check_email last_check)
my $ok = check_email($email_addr);
print "DNS timeout\n"
    if last_check()->{code} == CU_DNS_TIMEOUT;

Or be a little extra and call it fully qualified, no imports, no drama:

use Mail::CheckUser;
my $res = Mail::CheckUser::check_email($email_addr);

---

🌸 DESCRIPTION 🌸

So this Perl module gives you routines for checking the validity of an email address. That's the whole vibe. 🦋

It makes several checks, in order:

1. It checks the syntax of an email address. (Grammar check but for emails.)
2. It checks if there any MX records or A records for the domain part of the email address. (DNS said what it said.)
3. It tries to connect to an email server directly via SMTP to check if mailbox is valid. Old versions of this module performed this check via the VRFY command. Now the module uses another check; it uses a combination of MAIL and RCPT commands which simulates sending an email. It can detect bad mailboxes in many cases. (Fake-sending an email, no cap, it's giving espionage but make it wholesome.)

If is possible to turn off some or all networking checks (items 2 and 3). See "GLOBAL VARIABLES".

This module was designed with CGIs (or any other dynamic Web content programmed with Perl) in mind. Usually it is required to quickly check e-mail addresses in forms. If the check can't be finished in reasonable time, the e-mail address should be treated as valid. This is the default policy. By default if a timeout happens the result of the check is treated as positive. This behavior can be overridden - see "GLOBAL VARIABLES". (Benefit of the doubt is literally the default setting, we love a generous queen 👑)

---

🚨 IMPORTANT WARNING 🚨

Bestie, sit down. In many cases there is no way to detect the validity of email addresses with network checks. For example, non-monolithic mail servers (such as Postfix and qmail) often report that a user exists even if it is not so. This is because in cases where the work of the server is split among many components, the SMTP server may not know how to check for the existence of a particular user. Systems like these will reject mail to unknown users, but they do so after the SMTP conversation. In cases like these, the only absolutely sure way to determine whether or not a user exists is to actually send a mail and wait to see if a bounce messages comes back. Obviously, this is not a workable strategy for this module. Does it mean that the network checks in this module are useless? No. For one thing, just the DNS checks go a long way towards weeding out mistyped domain parts. Also, there are still many SMTP servers that will reject a bad address during the SMTP conversation. Because of this, it's still a useful part of checking for a valid email address. And this module was designed such that if there is exists possibility (however small) that the email address is valid, it will be treated as valid by this module. 💀

Another warning is about $Mail::CheckUser::Treat_Timeout_As_Fail global variable. Use it carefully - if it is set to true then some valid email addresses can be treated as bad simply because an SMTP or DNS server responds slowly. 😭

Another warning is about $Mail::CheckUser::Treat_Full_As_Fail global variable. Use it carefully - if it is set to true then some valid email addresses can be treated as bad simply because their mailbox happens to be temporarily full.

So real talk: this module is a bestie who assumes the best in everyone, and that's by design. Don't flip those globals to true unless you know what you're doing, because you will be calling perfectly good emails fake. 🙈

---

🌈 EXAMPLE 🌈

This simple script checks if email address blabla@foo.bar is valid.

use Mail::CheckUser qw(check_email last_check);

my $email = 'blabla@foo.bar';

if(check_email($email)) {
    print "E-mail address <$email> is OK\n";
} else {
    print "E-mail address <$email> isn't valid: ",
          last_check()->{reason}, "\n";
}

Look at her go. Simple, clean, prints a cute lil message either way. 🎀

---

🫶 SUBROUTINES 🫶

$ok = check_email($email)

Validates email address $email. Return true if email address is valid and false otherwise.

$res = last_check()

Returns detailed result of last check made with "check_email" as hash reference:

{ ok => OK, code => CODE, reason => REASON }

OK

True if last checked email address is valid. False otherwise.

CODE

A number which describes result of last check. See "CONSTANTS".

REASON

A string which describes result of last check.

---

💅 CONSTANTS 💅

Constants used by "last_check" to describe result of last check can be exported with

use Mail::CheckUser qw(:constants)

List of all defined constants:

• CU_OK — Check is successful. ✨
• CU_BAD_SYNTAX — Bad syntax of email address.
• CU_UNKNOWN_DOMAIN — Mail domain mentioned in email address is unknown.
• CU_DNS_TIMEOUT — Timeout has happen during DNS checks.
• CU_UNKNOWN_USER — User is unknown on SMTP server.
• CU_SMTP_TIMEOUT — Timeout has happen during SMTP checks.
• CU_SMTP_UNREACHABLE — All SMTP servers for mail domain were found unreachable during SMTP checks.
• CU_MAILBOX_FULL — Mailbox is temporarily full but probably a valid username.

---

🦋 GLOBAL VARIABLES 🦋

It is possible to configure "check_email" using the global variables listed below. (Yes, globals. Old school. We respect the heritage. 💜)

• $Mail::CheckUser::Skip_Network_Checks — If true then do only syntax checks. By default it is false.
• $Mail::CheckUser::Skip_SMTP_Checks — If it is true then do not try to connect to mail server to check if a user exists. If this is true, and $Mail::CheckUser::Skip_Network_Checks is false, only syntax and DNS checks are performed. By default it is false.
• $Mail::CheckUser::Skip_SYN — By default Net::Ping is used to determine remote reachability of SMTP servers before doing SMTP checks. Setting this to true skips this check. By default it is false.
• $Mail::CheckUser::Sender_Addr — MAIL/RCPT check needs an email address to use as the 'From' address when performing its checks. The default value is check@user.com.
• $Mail::CheckUser::Helo_Domain — Sender domain used in HELO SMTP command. If undef Net::SMTP is allowed to use its default value. By default it is undef.
• Mail::CheckUser::Timeout — Timeout in seconds for network checks. By default it is 60.
• $Mail::CheckUser::Treat_Timeout_As_Fail — If it is true "Mail::CheckUser" treats checks that time out as failed. By default it is false.
• $Mail::CheckUser::Treat_Full_As_Fail — If it is true "Mail::CheckUser" treats error "552 mailbox full" as an invalid email and sets CU_MAILBOX_FULL. By default it is false.
• $Mail::CheckUser::Treat_Grey_As_Fail — If it is true "Mail::CheckUser" treats all 400's errors as an invalid email and sets CU_TRY_AGAIN. By default it is false.
• $Mail::CheckUser::Net_DNS_Resolver — Override with customized Net::DNS::Resolver object. This is used to lookup MX and A records for the email domain when network checks are enabled. If undef, Net::DNS::Resolver->new will be used. The default value is undef.
• $Mail::CheckUser::Debug — If it is true then enable debug output on "STDERR". By default it is false.

---

⭐ AUTHORS ⭐

Ilya Martynov ilya@martynov.org

Rob Brown bbb@cpan.org

Module maintained at Source Forge ( http://sourceforge.net/projects/mail-checkuser/ ).

---

🎀 COPYRIGHT 🎀

Copyright (c) 1999-2003 by Ilya Martynov. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

$Id: CheckUser.pm,v 1.46 2003/09/18 23:51:36 hookbot Exp $

---

👑 SEE ALSO 👑

perl(1).

---

And that's the whole page, bestie!! 🌸 This was CheckUser(3pm) from the perl v5.34.0 docs, dated 2022-06-15 — go forth and validate those emails responsibly, mwah 💖✨