imme_add_recipient - Associates a recipient to a message being enqueued
#include <imta.h>
int imme_add_recipient(imme_t me, int rcpt_type, int flags, const char *adr, const char *origadr);
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 conform to RFC 822.
imme_add_recipient() must be called only after having specified 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 useful 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:
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 information 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 materialized by flags. which is a bitwise OR of zero or more of the following constants:
The default behavior, obtained by setting flags to 0, is equivalent to specifying IM_NOTIFY_DELAY | IM_NOTIFY_FAILURE
imme_add_recipient() returns IMRC_OK when successful.
Otherwise, one of the following error codes is returned:
The given recipient address cannot be routed. Check the existence of the recicient or the routing configuration with imta test -rewrite.
imta_error() can be called to get a textual message explaining the error.
_______________________________________
imme_init(3) , imme_error(3) , imme_start_header(3)