Ubuntu Manpage: Mail::CheckUser - check email addresses for validity

Provided by: libmail-checkuser-perl_1.24-2_all

NAME

       Mail::CheckUser - check email addresses for validity

SYNOPSIS

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

           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;

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

DESCRIPTION

       This Perl module provides routines for checking validity of email address.

       It makes several checks:

       1.  It checks the syntax of an email address.

       2.  It checks if there any MX records or A records for the domain part of the email address.

       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.

       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".

IMPORTANT WARNING

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.

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";
           }

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.

       $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 $