NAME

     immd_recipient_disposition - NOTARY routine


SYNOPSIS

     #include <imta.h>

     int  immd_recipient_disposition( immd_t d, const char *rcpt,
     const char *orcpt, const char *reason, im_disp_t disp);


DESCRIPTION

     This set of functions is used by channel programs to support
     NOTARY,  that is the generation of Delivery Status Notifica-
     tions (DSN) per RFC 1891.

     immd_recipient_disposition() can be used to  communicate  to
     the mail server the delivery status of a recipient described
     by its address rcpt and original address, orcpt.

     The disposition disp associated with the recipient is stored
     by  the  library  so that an appropriate action can be taken
     when immd_dequeue() is called.

     The available values for the disposition argument, and their
     effects are the following:

     IM_DISP_DEFERRED  The message could not be delivered to this
                       recipient,  owing  to a temporary failure.
                       If this is the only recipient, or if there
                       are  no other recipient with a disposition
                       of IM_DISP_DEFERRED, the message  will  be
                       deferred  when calling immd_dequeue().  If
                       there are other recipients with  different
                       disposition,   the  message  will  be  re-
                       enqueued for only those  recipients  whose
                       disposition is IM_DISP_DEFERRED.

     IM_DISP_DELIVERED The   message   has   been    successfully
                       delivered  for  this recipient.  Upon cal-
                       ling immd_dequeue() the  message  will  be
                       removed  from  the queue.  If requested by
                       the  NOTARY  flags,  a  positive   message
                       disposition  notification  may  be sent to
                       the originator.  IM_DISP_FAILED  The  mes-
                       sage  has  been successfully delivered for
                       this     recipient.      Upon      calling
                       immd_dequeue() the message will be removed
                       from the queue and returned to the  origi-
                       nator.   If requested by the NOTARY flags,
                       the notification will include a  "delivery
                       failed" status for this user.

     IM_DISP_RELAYED   The message has been successfully  relayed
                       to  to a non-NOTARY mail component incapa-
                       ble of preserving the NOTARY  information.
                       Upon  calling  immd_dequeue()  the message
                       will be removed from the queue.

     IM_DISP_RELAYED_FOREIGN
                       The message has been  successfully  handed
                       off to a non-NOTARY mail component incapa-
                       ble of preserving the NOTARY  information.
                       Upon  calling  immd_dequeue()  the message
                       will be removed from the queue.

     IM_DISP_RETURN    The message has been deemed  undeliverable
                       for    this    recipient.   Upon   calling
                       immd_dequeue() the message will be removed
                       from  the queue and returned to the origi-
                       nator, if requested by the NOTARY flags.

     IM_DISP_TIMEDOUT  The message has been deemed  undeliverable
                       for  this  recipient, after unsuccessfully
                       attempting  to  deliver  too  many  times.
                       Upon  calling  immd_dequeue()  the message
                       will  be  removed  from  the   queue   and
                       returned  to  the originator, if requested
                       by the NOTARY flags. The notification will
                       include  a "delivery timed out" status for
                       this user.  If the message is  re-enqueued
                       for  some  recipients,  rcpt will not be a
                       recipient of this message.

     reason can be used to include a more human readable explana-
     tion of the delivery status in the DSN message.

     md is the dequeue context used for this message.


RETURN VALUES

     All these functions return IMRC_OK when successful, and  one
     of the following error codes otherwise:

     IMRC_BAD_CONTEXT
                 The dequeue context md has not been  initialized
                 or  has  been  corrupted.  Make sure immd_init()
                 has been previously called.

     IMRC_INVALID_RECIPIENT_DISPOSITION
                 The     value     of     disp     passed      to
                 immd_recipient_disposition() does not correspond
                 to any valid delivery status.

     IMRC_NO_RECIPIENT
                 rcpt passed to  immd_recipient_disposition()  is
                 NULL   or  does  not  correspond  to  any  valid
                 recipient of this message.

     A textual explanation of the failure can be obtained by cal-
     ling imta_error() immediately afterwards.


ATTRIBUTES


NOTES

     In a previous release of the SIMS SDK,  Notary  support  was
     implemented      through      the      immd_return()     and
     immd_return_add_entry()   interfaces.    immd_return()   and
     immd_return_add_entry() are obsolete and should no longer be
     used, even though binary compatibility and approximate func-
     tionality  are  maintained in the short term.  immd_return()
     no longer does anything, as what it used to do is  now  done
     by   immd_dequeue(),   which   had   to  be  called  anyway.
     immd_return_add_entry()  provides  approximately  the   same
     functionality  that  immd_recipient_disposition()  provides,
     except that it takes a delivery status status as opposed  to
     a recipient disposition.

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


SEE ALSO

     immd_get_recipient(3), immd_dequeue(3), imta_error(3)