NAME

       Qpsmtpd::Address - Lightweight E-Mail address objects

DESCRIPTION

       Based originally on cut and paste from Mail::Address and including every jot and tittle from
       RFC-2821/2822 on what is a legal e-mail address for use during the SMTP transaction.

USAGE

         my $rcpt = Qpsmtpd::Address->new('<email.address@example.com>');

       The objects created can be used as is, since they automatically stringify to a standard form, and they
       have an overloaded comparison for easy testing of values.

METHODS

   new()
       Can be called two ways:

       •   Qpsmtpd::Address->new('<full_address@example.com>')

           The  normal  mode  of  operation is to pass the entire contents of the RCPT TO: command from the SMTP
           transaction.  The value will be fully parsed via the canonify method, using the full RFC 2821 rules.

       •   Qpsmtpd::Address->new("user", "host")

           If the caller has already split the address from the domain/host, this mode  will  not  canonify  the
           input values.  This is not recommended in cases of user-generated input for that reason.  This can be
           used  to  generate Qpsmtpd::Address objects for accounts like "<postmaster>" or indeed for the bounce
           address "<>".

       The resulting objects can be stored in  arrays  or  used  in  plugins  to  test  for  equality  (like  in
       badmailfrom).

   canonify()
       Primarily  an  internal  method,  it is used only on the path portion of an e-mail message, as defined in
       RFC-2821 (this is the part inside the angle brackets and does not include the "human readable" portion of
       an address).  It returns a list of (local-part, domain).

   parse()
       Retained as a compatibility method, it is completely equivalent to new() called with a single parameter.

   address()
       Can be used to reset the value of an existing Q::A object, in which case it takes  a  parameter  with  or
       without the angle brackets.

       Returns  the stringified representation of the address.  NOTE: does not escape any of the characters that
       need escaping, nor does it include the surrounding angle brackets.  For that purpose, see format.

   format()
       Returns the canonical stringified representation of the address.  It does escape any characters requiring
       it (per RFC-2821/2822) and it does include the surrounding  angle  brackets.   It  is  also  the  default
       stringification operator, so the following are equivalent:

         print $rcpt->format();
         print $rcpt;

   user([$user])
       Returns the "localpart" of the address, per RFC-2821, or the portion before the '@' sign.

       If called with one parameter, the localpart is set and the new value is returned.

   host([$host])
       Returns the "domain" part of the address, per RFC-2821, or the portion after the '@' sign.

       If called with one parameter, the domain is set and the new value is returned.

   notes($key[,$value])
       Get or set a note on the address. This is a piece of data that you wish to attach to the address and read
       somewhere else. For example you can use this to pass data between plugins.

COPYRIGHT

       Copyright 2004-2005 Peter J. Holzer.  See the LICENSE file for more information.

perl v5.40.1                                       2025-03-21                              Qpsmtpd::Address(3pm)