Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference

`mtaEnqueueTo()`

Add an envelope recipient to a message being submitted.

Syntax

int mtaEnqueueTo(mta_nq_t   *nq_ctx,
                 const char *to_adr,
                 size_t      to_adr_len,
                 int         item_code, ...);

Arguments

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`.

Description

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().

Note –

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
`MTA_BCC`	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.
`MTA_CC`	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.
`MTA_NOTIFY_FLAGS`	`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: The pointer to the original recipient address. The length in bytes of that address. If a value of zero is supplied for the length, then the address string must be NULL terminated.
`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: The address of a pointer to receive the address of the NULL terminated error text. The address of a `size_t` to receive the length of that error text. A value of NULL can be passed for the `errmsg_len` argument.
`MTA_TO`	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()`.

Return Values

Return Values	Description
`0`	Normal, successful completion.
`MTA_BADARGS`	This value is returned for one of the following reasons: A NULL value was supplied for the `nq_ctx` call argument. An invalid enqueue context was supplied for `nq_ctx`. A required argument to an item code was NULL.
`MTA_NO`	If `MTA_DQ_CONTEXT` was specified, then the supplied envelope `To:` address does not match any envelope recipient address in the queued message represented by the supplied dequeue context. Otherwise, the MTA rejected the envelope recipient address. It could be syntactically invalid, refused by a mapping table, such as `SEND_ACCESS`. Consider using the `MTA_REASON` item code.
`MTA_NOSUCHITEM`	An invalid item code was specified.
`MTA_ORDER`	The call was made out of order: the message’s envelope recipient list has already been terminated by a call to `mtaEnqueueWrite()` or `mtaEnqueueWriteLine()`.
`MTA_STRTRUERR`	The supplied envelope `To:` address or original envelope To: address is too long. Neither may exceed a length of `ALFA_SIZE` bytes.

Example

This routine is used in Example 5–2.