Specify the delivery status (disposition) of an envelope recipient address.
int mtaDequeueRecipientDisposition(mta_dq_t *dq_ctx, const char *env_to, size_t env_to_len, size_t disposition, int item_code, ...); |
Arguments |
Description |
---|---|
dq_ctx |
A dequeue context created by mtaDequeueStart(). |
env_to |
The recipient address to effect the setting for. This must be the recipient’s envelope To: address as returned by mtaDequeueRecipientNext() and not some transformation of that address. If a value of zero is passed for the env_to_len argument, then this string must be NULL terminated. |
env_to_len |
The length in bytes of the recipient address, env_to. This length does not include any NULL terminator. If a value of zero is passed for this argument, then the recipient address string must be NULL terminated. |
disposition |
The delivery status disposition to set for this recipient address. See the description section that follows for further details. |
item_code |
An optional list of item codes. See the description section that follows for a list of item codes. The list must be terminated with an integer argument with value 0. |
Before completing processing of a queued message, the disposition of each envelope recipient must be set either by repeated calls to mtaDequeueRecipientDisposition(), or by means of the MTA_DISP item code for mtaDequeueMessageFinish(). For the former, a call should be made for each envelope recipient address. For the latter, the disposition set with MTA_DISP applies to all envelope recipients, overriding any previous settings made with mtaDequeueRecipientDisposition(). The delivery status dispositions, and their descriptions are listed in the table that follows. Pass one of these values for the disposition argument.
Delivery Status Dispositions |
Description |
---|---|
MTA_DISP_DEFERRED |
Processing for this recipient has experienced a temporary failure (for example, the network is temporarily down, the disk is currently full, the recipient is presently over quota). Schedule a later processing attempt for this recipient. |
MTA_DISP_DELIVERED |
Final delivery has been effected for this recipient address. Any required delivery notifications should be generated. Intermediate processing channels should use MTA_DISP_RELAYED rather than MTA_DISP_DELIVERED. Use of MTA_DISP_DELIVERED by an intermediate processing channel might incorrectly generate a delivery status notification when final delivery has not yet been effected. |
MTA_DISP_FAILED |
Processing for this recipient has experienced a permanent failure. The message is and will remain undeliverable for this recipient. No further delivery attempts are to be made for this recipient. Any required non-delivery notifications should be generated. |
MTA_DISP_RELAYED |
The message has been successfully processed for this recipient. No further processing by this channel is needed for this recipient address. No delivery status notification is generated as final delivery will be effected by another entity capable of generating any needed notification messages. This disposition should be used by intermediate processing channels. It should also be used by gateways that transfer the message to other mail systems capable of generating the necessary notification messages. |
MTA_DISP_RELAYED_FOREIGN |
The message has been successfully processed for this recipient. No further processing by this channel is needed for this recipient address; however, a relayed delivery status notification should be generated if delivery notification was requested for this recipient. This disposition should be used by gateways that transfer the message to other mail systems incapable of generating the necessary notification messages. |
MTA_DISP_RETURN |
Generate a postmaster non-delivery notification for this recipient and, for this recipient, remove the message from the channel’s queue. This disposition is not intended for use by channels. Instead, it should be used by postmaster utilities that allow the postmaster to manually return mail messages. |
MTA_DISP_TIMEDOUT |
Generate a timed-out non-delivery notification indicating that the message has been undeliverable for too long and no further delivery attempts will be made. This disposition is not intended for use by channels. Instead, it is meant for use by the MTA return job that scans the MTA queues, returning old, undeliverable messages to their originators. |
This table lists the item codes for this routine, and the additional required arguments, and gives a description of each.
Item Codes |
Additional Arguments |
Description |
---|---|---|
MTA_DISP |
size_t disposition |
Use the MTA_DISP item code to set the disposition for all recipients of the message. This disposition will override any prior disposition settings. This item code must be followed by one additional call argument: the disposition value to set. See the description of mtaDequeueRecipientDisposition() for a discussion of the disposition settings. |
MTA_ITEM_LIST |
mta_item_list_t *item_list |
Specify a pointer to an item list array. The item list array must be terminated with a final array entry with an item code value of zero. For further information on item list usage, see Item Codes and Item Lists. |
MTA_REASON |
const char *reason size_t reason_len |
The reason for ascribing the disposition to this recipient address. This reason might then appear in any delivery or non-delivery status notification for that recipient. This item code must be followed by two additional call arguments:
|
This code fragment assumes a condition in which the recipient address is invalid. It returns a disposition of MTA_DISP_FAILED with an explanation.
mtaDequeueRecipientDisposition( dq_ctx, "sue@siroe.com", 0, MTA_DISP_FAILED, MTA_REASON, "Invalid recipient address: no such user", 0, 0); |