NAME

       Sendmail::PMilter::Context - per-connection milter context

DESCRIPTION

       A Sendmail::PMilter::Context is the context object passed to milter callback functions as the first
       argument, typically named "$ctx" for convenience.  This manual explains publicly accessible operations on
       $ctx.

METHODS

       $ctx->getpriv
           Returns  the  private  data  object  for  this  milter  instance, set by $ctx->setpriv() (see below).
           Returns undef if setpriv has never been called by this milter instance.

       $ctx->getsymval(NAME)
           Retrieves the macro symbol named NAME from  the  macros  available  from  the  MTA  for  the  current
           callback.   This typically consists of a one-letter macro name, or a multi-letter macro name enclosed
           in {curly braces}.  If the requested macro was not defined by  the  MTA  ny  the  time  getsymval  is
           called, returns undef.

           Some  common  macros  include  the  following.   (Since milter is a protocol first implemented in the
           Sendmail MTA, the macro names are the same as those in Sendmail itself.)

           $ctx->getsymval('_')
             The remote host name and address, in standard SMTP "name [address]" form.

           $ctx->getsymval('i')
             The MTA's queue ID for the current message.

           $ctx->getsymval('j')
             The MTA's idea of local host name.

           $ctx->getsymval('{if_addr}')
             The local address of the network interface upon which the connection was received.

           $ctx->getsymval('{if_name}')
             The local hostname of the network interface upon which the connection was received.

           $ctx->getsymval('{mail_addr}')
             The MAIL FROM: sender's address, canonicalized and angle bracket stripped.  (This is typically  not
             the  same  value  as  the second argument to the "envfrom" callback.)  Will be defined to the empty
             string '' if the client issued a MAIL FROM:<> null return path command.

           $ctx->getsymval('{rcpt_addr}')
             The RCPT TO: recipient's address, canonicalized and angle bracket stripped.  (This is typically not
             the same value as the second argument to the "envrcpt" callback.)

           Not all macros may be available at all times, of course.  Some macros  are  only  available  after  a
           specific  phase  is  reached, and some macros may only be available from certain MTA implementations.
           Care should be taken to check for undef returns in order to cover these cases.

       $ctx->setpriv(DATA)
           This is the place to store  milter-private  data  that  is  sensitive  to  the  current  SMTP  client
           connection.   Only one value can be stored, so typically an arrayref or hashref is initialized in the
           "connect" callback and set with $ctx->setpriv.

           This value can be retrieved on subsequent callback runs with $ctx->getpriv.

       $ctx->setreply(RCODE, XCODE, MESSAGE)
           Set an extended SMTP status reply (before returning SMFIS_REJECT or SMFIS_TEMPFAIL).  RCODE should be
           a short (4xx or 5xx) numeric reply code, XCODE should be a long  ('4.x.x'  or  '5.x.x')  ESMTP  reply
           code, and MESSAGE is the full text of the message to send.  Example:

                   $ctx->setreply(451, '4.7.0', 'Cannot authenticate you right now');
                   return SMFIS_TEMPFAIL;

           Note  that  after  setting  a  reply with this method, the SMTP result code comes from RCODE, not the
           difference between SMFIS_REJECT or SMFIS_TEMPFAIL.  However, for consistency, callbacks  that  set  a
           4xx  response  code  should  use  SMFIS_TEMPFAIL,  and  those  that  set  a  5xx  code  should return
           SMFIS_REJECT.

           Returns a true value on success, undef on failure.  In the case of failure, typically only caused  by
           bad parameters, a generic message will still be sent based on the SMFIS_* return code.

       $ctx->shutdown()
           A  special  case  of  "$ctx->setreply()" which sets the short numeric reply code to 421 and the ESMTP
           code to 4.7.0.  Under Sendmail 8.13 and higher, this  will  close  the  MTA's  communication  channel
           quickly,  which  should  immediately  result  in  a  "close"  callback  and  end of milter execution.
           (However, Sendmail 8.11-8.12 will treat this as a regular 4xx error and will continue processing  the
           message.)

           Always returns a true value.

           This method is an extension that is not available in the standard Sendmail::Milter package.

       $ctx->addheader(HEADER, VALUE)
           Add  header HEADER with value VALUE to this mail.  Does not change any existing headers with the same
           name.  Only callable from the "eom" callback.

           Returns a true value on success, undef on failure.

       $ctx->addrcpt(ADDRESS)
           Add address ADDRESS to the list of recipients for this mail.  Only callable from the "eom" callback.

           Returns a true value on success, undef on failure.

       $ctx->chgheader(HEADER, INDEX, VALUE)
           Change the INDEX'th header of name HEADER to the value VALUE.  Only callable from the "eom" callback.

           Returns a true value on success, undef on failure.

       $ctx->delrcpt(ADDRESS)
           Remove address ADDRESS from the list of recipients for this mail.  The ADDRESS argument must match  a
           prior  argument  to  the  "envrcpt" callback exactly (case sensitive, and including angle brackets if
           present).  Only callable from the "eom" callback.

           Returns a true value on success, undef on failure.  A success return does  not  necessarily  indicate
           that the recipient was successfully removed, but rather that the command was queued for processing.

       $ctx->progress()
           Sends  an  asynchronous  "progress"  message  to  the  MTA,  which  should  reset  the MTA's internal
           communications timer.  This can allow longer than normal operations, such as a deliberate  delay,  to
           continue  running without dropping the milter-MTA connection.  This command can be issued at any time
           during any callback, although issuing it during a "close"  callback  may  trigger  socket  connection
           warnings in Perl.

           Always returns a true value.

           This method is an extension that is not available in the standard Sendmail::Milter package.

       $ctx->quarantine(REASON)
           Quarantine  the  current message in the MTA-defined quarantine area, using the given REASON as a text
           string describing the quarantine status.  Only callable from the "eom" callback.

           Returns a true value on success, undef on failure.

           This method is an extension that is not available in the standard Sendmail::Milter package.

       $ctx->replacebody(BUFFER)
           Replace the message body with the data in BUFFER (a scalar).  This  method  may  be  called  multiple
           times,  each  call  appending  to the replacement buffer.  End-of-line should be represented by CR-LF
           ("\r\n").  Only callable from the "eom" callback.

           Returns a true value on success, undef on failure.

       $ctx->setsender(ADDRESS)
           Replace  the  envelope  sender  address  for  the  given  mail  message.   This  method  provides  an
           implementation  to  access  the  mlfi_setsender  method added to the libmilter library as part of the
           mlfi-setsender project (http://www.sourceforge.net/projects/mlfi-setsender).

           Returns a true value on success, undef on failure.  A success return does  not  necessarily  indicate
           that the recipient was successfully removed, but rather that the command was queued for processing.

SEE ALSO

       Sendmail::PMilter

perl v5.32.1                                       2021-12-26                    Sendmail::PMilter::Context(3pm)