Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CheckUser(3)	      User Contributed Perl Documentation	  CheckUser(3)

       Mail::CheckUser - check email addresses for validity

	   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);

       This Perl module	provides routines for checking validity	of email

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

       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.

       This simple script checks if email address "" is valid.

	   use Mail::CheckUser qw(check_email last_check);

	   my $email = '';

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

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

	       A number	which describes	result of last check.  See

	       A string	which describes	result of last check.

       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:

	   Check is successful.

	   Bad syntax of email address.

	   Mail	domain mentioned in email address is unknown.

	   Timeout has happen during DNS checks.

	   User	is unknown on SMTP server.

	   Timeout has happen during SMTP checks.

	   All SMTP servers for	mail domain were found unreachable during SMTP

	   Mailbox is temporarily full but probably a valid username.

       It is possible to configure "check_email" using the global variables
       listed below.

	   If true then	do only	syntax checks.	By default it is false.

	   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.

	   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/RCPT check needs an email address to use as the	'From' address
	   when	performing its checks.	The default value is "".

	   Sender domain used in HELO SMTP command.  If	undef Net::SMTP	is
	   allowed to use its default value.  By default it is undef.

	   Timeout in seconds for network checks.  By default it is 60.

	   If it is true "Mail::CheckUser" treats checks that time out as
	   failed.  By default it is false.

	   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.

	   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.

	   If it is true then enable debug output on "STDERR".	By default it
	   is false.

       Ilya Martynov

       Rob Brown

       Module maintained at Source Forge ( ).

       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:,v 1.46	2003/09/18 23:51:36 hookbot Exp	$


perl v5.32.0			  2003-09-18			  CheckUser(3)


Want to link to this manual page? Use this URL:

home | help