Add an envelope recipient to a message being submitted.
int mtaEnqueueTo(mta_nq_t *nq_ctx, const char *to_adr, size_t to_adr_len, int item_code, ...); |
Arguments |
Description |
---|---|
nq_ctx |
Pointer to an enqueue context created with mtaEnqueueStart(). |
to_adr |
An address to add to the message being enqueued. The address must be compliant with RFC 2822. When used as an envelope address, the MTA will reduce it to an RFC 2821 compliant transport address. If a value of zero is passed for to_adr_len the address string must be NULL terminated. The length of this string, not including any NULL terminator, may not exceed ALFA_SIZE bytes. |
to_adr_len |
The length in bytes, not including any NULL terminator, of the address supplied with to_adr. If a value of zero is passed for this argument, then the address string must be NULL terminated. |
item_code |
An optional list of item codes. See the description section below for a list of item codes. The list must be terminated with an integer argument with value 0. |
After initiating a message enqueue operation with mtaEnqueueStart(), the envelope recipient list for the message must to be constructed. This list is the actual list of recipients to which the message is to be delivered. A message must have at least one envelope recipient address; otherwise, there is no one to deliver the message to. In the envelope there is no distinction between To:, Cc:, or Bcc: addressees. Additionally, the list of addressees appearing in the message’s header need not be the same as those appearing in the envelope. This is the case with list-oriented mail. The address in the message’s header is often the list’s mail address; whereas, the addresses in the envelope are the those of the list’s individual members.
By default, when an address is added to a message with mtaEnqueueTo(), it is added as both an envelope recipient address as well as a To: addressee in the message’s To: header line. The address is therefore considered to be an active transport address as well as a header address. This case corresponds to the MTA_TO item code. To instead mark an active transport address for addition to either a Cc: or Bcc: header line, use the MTA_CC or MTA_BCC item code.
Addresses that only appear in the message’s header are sometimes referred to as inactive addresses. Such addresses added with mtaEnqueueTo() may be noted as such with the MTA_HDR_TO, MTA_HDR_CC, and MTA_HDR_BCC item codes. They can also be manually added by constructing the To:, Cc:, or Bcc: header lines with mtaEnqueueWrite() or mtaEnqueueWriteLine().
The MTA SDK will automatically generate multiple message copies when Bcc: recipients exist for the message. Specifically, when a message has N envelope recipient addresses which are Bcc: recipients, the MTA SDK will automatically generate N+1 message copies: one copy for each of the Bcc: recipients and an additional copy for the remaining, non-Bcc: recipients. Each copy for a Bcc: recipient will only disclose that Bcc: recipient in the message’s header. The message copy for all of the non-Bcc: recipients will disclose none of the Bcc: recipients in its header
An address may be added as only an active transport address without addition to any header line. This is done with the MTA_ENV_TO item code. This item code should be used by intermediate processing channels that copy verbatim the outer message header from the old message to the new, which prevents duplication of addresses in the new message’s header.
When an active transport address is added to a message, it is possible that the MTA will reject the address. For example, the address can be rejected when there is a mapping table, such as the SEND_ACCESS mapping table. When an address is rejected by the MTA, extended error text is made available by the MTA. This extended information can be captured through use of the MTA_REASON item code.
The following table lists the item codes for this routine, their additional arguments, and gives a description of each.
Item Codes |
Additional Arguments |
Description |
---|---|---|
None |
The address is an active transport address that should also appear in a Bcc: header line. The address will be added to both the envelope recipient list as well as the message’s header. For further information about Bcc:, see the note under Description. |
|
None |
The address is an active transport address that should also appear in a Cc: header line. As such, the address will be added to both the envelope recipient list as well as the message’s header. |
|
MTA_DELIVERY_FLAGS |
size_t dflags |
Specify additional envelope delivery flags to set for this recipient. The logical OR of any existing setting for the recipient and the value here supplied will be used for the recipient’s delivery flag setting. The existing setting for the recipient will be either the message’s setting, which was set with mtaEnqueueStart(), or any setting copied over from the dequeue context for this recipient with the MTA_DQ_CONTEXT item code. This item code should be followed by one additional call argument: the value to combine with any existing setting. |
MTA_DELIVERY_FLAGS_ABS |
size_t dflags |
Ignore any previous envelope delivery flag setting for the recipient and replace the setting with the value specified with this item code. This item code should be followed by one additional call argument: the delivery flag setting to effect. |
MTA_DQ_CONTEXT |
mta_dq_t *dq_ctx |
When a dequeue context is supplied using this item code, the specified envelope recipient address is compared to the envelope recipient list for the queued message represented by the dequeue context. If a match is found, envelope fields for the recipient are copied from the queued message to the new message being enqueued. If no match is found, an MTA_NO error status is returned. This item code must be followed by one additional argument: the pointer to the dequeue context to use. |
MTA_ENV_TO |
None |
The address is an active transport address; add it to the envelope recipient list. Do not add it to any header lines. This designation is often used by intermediate processing channels. |
MTA_HDR_BCC |
None |
The address is not an active transport address; do not add it to the envelope recipient list. The address should, however, be added to a Bcc: header line. Note that since a Bcc: header line is usually only placed in the message copy destined to the Bcc: recipient, use of this item code only arises when the Bcc: recipient’s header address differs from their transport address and, consequently, the two need to be added with separate calls to mtaEnqueueTo(). |
MTA_HDR_CC |
None |
The address is not an active transport address; do not add it to the envelope recipient list. The address should, however, be added to a Cc: header line. |
MTA_HDR_TO |
None |
The address is not an active transport address; do not add it to the envelope recipient list. The address should, however, be added to a To: header line. |
size_t nflags |
Delivery status notification flags specific to this envelope recipient address. A value specified with this item code overrides any setting made for the message itself when the enqueue context was created. It also overrides any value inherited from a dequeue context. Note that this item code has no effect when MTA_HDR_BCC, MTA_HDR_CC, or MTA_HDR_TO is specified; notification flags only apply to active transport addresses. For further details, see the description of this item code for mtaEnqueueStart(). This item code must be followed by one additional call argument: the address of an integer to receive the setting of the delivery status notification flags. |
|
MTA_ORCPT_TO |
const char *orcpt size_t orcpt_len |
Specify the original envelope recipient address in RFC 1891 original-recipient address format (for example, rfc822;sue@siroe.com for sue@siroe.com). This item code must be followed by two additional arguments:
|
MTA_REASON |
const char **errmsg size_t *errmsg_len |
Provide the address of a string pointer to receive any extended error message information. In the event of an error associated with submitting the recipient to the MTA, then the MTA may return additional information. By providing this pointer, that additional information may be obtained for diagnostic purposes. This item code should be followed by two additional item codes:
|
None |
The address is an active transport address that should also appear in a To: header line. This is the default interpretation of addresses added with mtaEnqueueTo(). |
This routine is used in Example 5–2.