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)