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

FreeBSD Manual Pages


home | help
Email::Address(3)     User Contributed Perl Documentation    Email::Address(3)

       Email::Address -	RFC 2822 Address Parsing and Creation

       version 1.912

	 use Email::Address;

	 my @addresses = Email::Address->parse($line);
	 my $address   = Email::Address->new(Casey => 'casey@localhost');

	 print $address->format;

       This class implements a regex-based RFC 2822 parser that	locates	email
       addresses in strings and	returns	a list of "Email::Address" objects
       found.  Alternatively you may construct objects manually. The goal of
       this software is	to be correct, and very	very fast.

       Version 1.909 and earlier of this module	had vulnerabilies
       (CVE-2015-7686 <
       bin/cvename.cgi?name=CVE-2015-7686>) and	(CVE-2015-12558
       <>)	which
       allowed specially constructed email to cause a denial of	service. The
       reported	vulnerabilities	and some other pathalogical cases (meaning
       they really shouldn't occur in normal email) have been addressed	in
       version 1.910 and newer.	 If you're running version 1.909 or older, you
       should update!

       Alternatively, you could	switch to Email::Address::XS which has a
       backward	compatible API.

   Package Variables
       ACHTUNG!	 Email isn't easy (if even possible) to	parse with a regex, at
       least if	you're on a "perl" prior to 5.10.0.  Providing regular
       expressions for use by other programs isn't a great idea, because it
       makes it	hard to	improve	the parser without breaking the	"it's a	regex"
       feature.	 Using these regular expressions is not	encouraged, and
       methods like "Email::Address->is_addr_spec" should be provided in the

       Several regular expressions used	in this	package	are useful to others.
       For convenience,	these variables	are declared as	package	variables that
       you may access from your	program.

       These regular expressions conform to the	rules specified	in RFC 2822.

       You can access these variables using the	full namespace.	If you want
       short names, define them	yourself.

	 my $addr_spec = $Email::Address::addr_spec;

	   This	regular	expression defined what	an email address is allowed to
	   look	like.

	   This	regular	expression defines an $addr_spec wrapped in angle

	   This	regular	expression defines what	an email address can look like
	   with	an optional preceding display name, also known as the

	   This	is the complete	regular	expression defining an RFC 2822	email
	   address with	an optional preceding display name and optional
	   following comment.

   Class Methods
	     my	@addrs = Email::Address->parse(
	       q[me@local, Casey <me@local>, "Casey" <me@local>	(West)]

	   This	method returns a list of "Email::Address" objects it finds in
	   the input string.  Please note that it returns a list, and expects
	   that	it may find multiple addresses.	 The behavior in scalar
	   context is undefined.

	   The specification for an email address allows for infinitely
	   nestable comments.  That's nice in theory, but a little over	done.
	   By default this module allows for one (1) level of nested comments.
	   If you think	you need more, modify the
	   $Email::Address::COMMENT_NEST_LEVEL package variable	to allow more.

	     $Email::Address::COMMENT_NEST_LEVEL = 10; # I'm deep

	   The reason for this hardly-limiting limitation is simple:

	   Long	strings	of whitespace can be problematic for this module to
	   parse, a bug	which has not yet been adequately addressed.  The
	   default behavior is now to collapse multiple	spaces into a single
	   space, which	avoids this problem.  To prevent this behavior,	set
	   $Email::Address::COLLAPSE_SPACES to zero.  This variable will go
	   away	when the bug is	resolved properly.

	   In accordance with RFC 822 and its descendants, this	module demands
	   that	email addresses	be ASCII only.	Any non-ASCII content in the
	   parsed addresses will cause the parser to return no results.

	     my	$address = Email::Address->new(undef, 'casey@local');
	     my	$address = Email::Address->new('Casey West', 'casey@local');
	     my	$address = Email::Address->new(undef, 'casey@local', '(Casey)');

	   Constructs and returns a new	"Email::Address" object. Takes four
	   positional arguments: phrase, email,	and comment, and original

	   The original	string should only really be set using "parse".


	   One way this	module stays fast is with internal caches. Caches live
	   in memory and there is the remote possibility that you will have a
	   memory problem. On the off chance that you think you're one of
	   those people, this class method will	empty those caches.

	   I've	loaded over 12000 objects and not encountered a	memory

	     Email::Address->disable_cache if memory_low();

	   If you'd rather not cache address parses at all, you	can disable
	   (and	re-enable) the Email::Address cache with these methods.	 The
	   cache is enabled by default.

   Instance Methods
	     my	$phrase	= $address->phrase;
	     $address->phrase( "Me oh my" );

	   Accessor and	mutator	for the	phrase portion of an address.

	     my	$addr =	$address->address;
	     $addr->address( ""	);

	   Accessor and	mutator	for the	address	portion	of an address.

	     my	$comment = $address->comment;
	     $address->comment(	"(Work address)" );

	   Accessor and	mutator	for the	comment	portion	of an address.

	     my	$orig =	$address->original;

	   Accessor for	the original address found when	parsing, or passed to

	     my	$host =	$address->host;

	   Accessor for	the host portion of an address's address.

	     my	$user =	$address->user;

	   Accessor for	the user portion of an address's address.

	     my	$printable = $address->format;

	   Returns a properly formatted	RFC 2822 address representing the

	     my	$name =	$address->name;

	   This	method tries very hard to determine the	name belonging to the
	   address.  First the "phrase"	is checked. If that doesn't work out
	   the "comment" is looked into. If that still doesn't work out, the
	   "user" portion of the "address" is returned.

	   This	method does not	try to massage any name	it identifies and
	   instead leaves that up to someone else. Who is it to	decide if
	   someone wants their name capitalized, or if they're Irish?

   Overloaded Operators
	     print "I have your	email address, $address.";

	   Objects stringify to	"format" by default. It's possible that	you
	   don't like that idea. Okay, then, you can change it by modifying
	   $Email:Address::STRINGIFY. Please consider modifying	this package
	   variable using "local". You might step on someone else's toes if
	   you don't.

	       local $Email::Address::STRINGIFY	= 'host';
	       print "I	have your address, $address.";
	     print "I have your	address, $address.";
	     #	 "Casey	West" <>

	   Modifying this package variable is now deprecated. Subclassing is
	   now the recommended approach.

   Did I Mention Fast?
       On his 1.8GHz Apple MacBook, rjbs gets these results:

	 $ perl	-Ilib bench/	bench/corpus.txt 5
			  Rate	Mail::Address Email::Address
	 Mail::Address	2.59/s		   --		-44%
	 Email::Address	4.59/s		  77%		  --

	 $ perl	-Ilib bench/	bench/corpus.txt 25
			  Rate	Mail::Address Email::Address
	 Mail::Address	2.58/s		   --		-67%
	 Email::Address	7.84/s		 204%		  --

	 $ perl	-Ilib bench/	bench/corpus.txt 50
			  Rate	Mail::Address Email::Address
	 Mail::Address	2.57/s		   --		-70%
	 Email::Address	8.53/s		 232%		  --

       ...unfortunately, a known bug causes a loss of speed the	string to
       parse has certain known characteristics,	and disabling cache will also
       degrade performance.

       Thanks to Kevin Riggle and Tatsuhiko Miyagawa for tests for annoying
       phrase-quoting bugs!

       o   Casey West

       o   Ricardo SIGNES <>

       o   Alex	Vandiver <>

       o   David Golden	<>

       o   David Steinbrunner <>

       o   Glenn Fowler	<>

       o   Jim Brandt <>

       o   Kevin Falcone <>

       o   Pali	<>

       o   Ruslan Zakirov <>

       o   sunnavy <>

       o   William Yardley <>

       This software is	copyright (c) 2004 by Casey West.

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

perl v5.32.0			  2018-12-31		     Email::Address(3)


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

home | help