NAME

     imme_add_recipient - Associates a  recipient  to  a  message
     being enqueued


SYNOPSIS

     #include <imta.h>

     int imme_add_recipient(imme_t me, int rcpt_type, int  flags,
     const char *adr, const char *origadr);


DESCRIPTION

     When enqueuing a mail message, the list  of  To:,  Cc:,  and
     Bcc:  recipients  is  built  up,  one  address at a time, by
     repeatedly calling imme_add_recipient  This  information  is
     then  used  to  construct the message's envelope To: address
     list as well as the To:, Cc:, and Bcc:  header  lines  which
     will  appear in the message header. Each address should con-
     form to RFC 822.

     imme_add_recipient() must be called only after having speci-
     fied  the From: envelope address with imme_start_envelope(),
     and before having written the message header.

     adr must be set to the recipient's  address,  while  origadr
     may  optionally  be  set to the recipient's original address
     specified by the real originator, before it was rewritten by
     intermediate  mail system along the way.  This field is use-
     ful when gatewaying to and from certain  mail  environments,
     such as X.400.

     rcpt_type specifies whether the added recipient is to appear
     in  the  envelope to: address list, and/or as a To:, Cc:, or
     Bcc: address.  It is a bitwise OR of zero  or  more  of  the
     following constants:

     IM_RCPT_ENV       Envelope recipient

     IM_RCPT_TO        To: recipient

     IM_RCPT_CC        Cc: recipient

     IM_RCPT_BCC       Bcc: recipient

     The default behavior, obtained by setting recipient_type  to
     0, is equivalent to specifying IM_RCPT_ENV | IM_RCPT_TO

     In the message envelope, there  is  no  distinction  between
     To:,  Bcc:,  and Bcc: addresses. The recipient type informa-
     tion becomes useful only when creating the message header.

     Note that  any  combination  of  IM_RCPT_TO,  IM_RCPT_CC  or
     IM_RCPT_BCC,  can  simultaneously be set true. For instance,
     if rcpt_type has a value of IM_RCPT_TO |  IM_RCPT_BCC,  then
     the  recipient's  address  will be added to both To: and Cc:
     message header lines.

     Note that the same address may be specified more than  once.
     This may or may not result in multiple copies of the message
     being sent to that address.  SIMS will attempt to deliver  a
     copy of the message to each instance of a specified address;
     however, some mail  systems  receiving  the  mail  may  only
     deliver  a  single  copy  of  the message to each recipient,
     regardless of how many times  a  recipient  appears  in  the
     envelope To: address list.

     The notary information related to this recipient is  materi-
     alized  by  flags.  which is a bitwise OR of zero or more of
     the following constants:

     IM_NOTIFY_FAILURE     to request a DSN if the  delivery  has
                           failed permanently

     IM_NOTIFY_SUCCESS     to request a DSN if  the  delivery  is
                           successful

     IM_NOTIFY_DELAY       to request a DSN if the  delivery  has
                           failed temporarily

     IM_NOTIFY_NEVER       to request that a DSN not be generated
                           under any circumstances.

     The default behavior, obtained by setting  flags  to  0,  is
     equivalent to specifying IM_NOTIFY_DELAY | IM_NOTIFY_FAILURE


RETURN VALUES

     imme_add_recipient() returns IMRC_OK when successful.

     Otherwise, one of the following error codes is returned:

     IMRC_BAD_CONTEXT      The enqueue context me  has  not  been
                           initialized  or  has  been  corrupted.
                           Make sure imme_init() has been  previ-
                           ously called.

     IMRC_NO_ENVELOPE
                 The message envelope has not been created.  Call
                 imme_start_envelope() to create it.

     IMRC_NO_RECIPIENT
                 adr is nil.

     IMRC_INVALID_NOTARY_FLAGS
                 The value of flags  does  not  correspond  to  a
                 valid set of notary flags.

     IMRC_INVALID_ADDRESS

     The given recipient address cannot  be  routed.   Check  the
     existence of the recicient or the routing configuration with
     imta test -rewrite.

     IMRC_NOT_AUTHORIZED
                 The originator of the message is not allowed  to
                 send  mail  to adr.  Check email access restric-
                 tions and distribution list restrictions if  the
                 specified   recipient  is  a  distribution  list
                 alias.

     IMRC_ADDRESS_TOO_LONG
                 adr is more than IMADR_ADDRESS_LEN  bytes  long.
                 This restrictionis imposed by RFC 822.

     imta_error() can be called to get a textual message explain-
     ing the error.


ATTRIBUTES

               _______________________________________
              |   Attribute Type   |  Attribute Value|
              |____________________|_________________|
              | Architecture       |  sparc, x86     |
              |____________________|_________________|
              | Availability       |  SUNWimsdk      |
              |____________________|_________________|
              | MT-Level           |  MT-Safe        |
              |____________________|_________________|
              | Interface Stability|  Stable         |
              |____________________|_________________|


SEE ALSO

     imme_init(3), imme_error(3), imme_start_header(3)