How to Reject a Recipient or a Message in a Transport Agent

The agent can handle the OnRcptCommand event if it wants to reject recipients at the protocol level. If the agent decides that it does not want to allow the message to be delivered to this recipient, but it doesn’t want to block the whole message, it can reject the current recipient. This results in a rejection of the recipient at the SMTP protocol level; therefore, a DSN does not have to be generated.

For example, the following agent handles the OnRcptCommand event, determines whether the current recipient should be blocked, and then calls a method on the source object to block the recipient, if necessary.

    public class SampleSmtpReceiveAgent : SmtpReceiveAgent
    {
        private static SmtpResponse rejectResponse =
            new SmtpResponse("500", "", "Recipient blocked");

        SampleSmtpReceiveAgent()
        {
            this.OnRcptCommand += new RcptCommandEventHandler(
                this.OnRcptCommandHandler);
        }

        private void OnRcptCommandHandler(
            ReceiveCommandEventSource source,
            RcptCommandEventArgs e)
        {
            if (this.ShouldBlockRecipient(
                    e.MailItem,
                    e.RecipientAddress))
            {
                source.RejectCommand(
                    SampleSmtpReceiveAgent.rejectResponse);
            }
        }

        private bool ShouldBlockRecipient(
            MailItem mailItem,
            RoutingAddress recipient)
        {
            // TODO: put logic here to decide whether to block 
            // the recipient.

            return false;
        }
    }

The agent can handle the OnEndOfHeaders or the OnEndOfData event if it wants to view the message headers or message body before it decides to drop some recipients but keep the whole message. If the agent decides to reject a recipient, it can call the EnvelopeRecipientCollection.Remove Method. This method has three overrides. The first two overrides take a single parameter, with a type of EnvelopeRecipient for the OnEndOfHeaders event or RoutingAddress for the OnEndOfData event. Each of these overrides silently drops the recipient from the message. The third override takes an EnvelopeRecipient, a DsnType, and an SmtpResponse. This override will drop the recipient and then send a DSN back to the sender if one was requested.

For example, the following agent handles the OnEndOfData event, and drops a recipient from the message.

    public class SampleSmtpReceiveAgent : SmtpReceiveAgent
    {
        private static SmtpResponse rejectResponse =
            new SmtpResponse("500", "", "Recipient rejected");

        public SampleSmtpReceiveAgent()
        {
            this.OnEndOfData += new EndOfDataEventHandler(
                this.OnEndOfDataHandler);
        }

        private void OnEndOfDataHandler(
            ReceiveMessageEventSource source, 
            EndOfDataEventArgs e)
        {
            foreach (EnvelopeRecipient recipient in e.MailItem.Recipients)
            {
                if (this.ShouldDropRecipient(e.MailItem, recipient))
                {
                    if (this.ShouldDropSilently())
                    {
                        e.MailItem.Recipients.Remove(recipient);
                    }
                    else
                    {
                        e.MailItem.Recipients.Remove(
                            recipient,
                            DsnType.Failure,
                            SampleSmtpReceiveAgent.rejectResponse);
                    }
                }
            }

        }

        private bool ShouldDropRecipient(
            MailItem mailItem,
            EnvelopeRecipient recipient)
        {
            // TODO: put logic here to decide whether to block
            // the recipient.

            return false;
        }

        private bool ShouldDropSilently()
        {
            // TODO: put logic here to decide whether to block
            // silently or send back a DSN.

            return false;
        }
    }

The agent can handle the OnEndOfHeaders or OnEndOfData event if it wants to reject messages at the protocol level. If it decides that it does not want to allow the message to be delivered to any recipient, it can reject the message. If the agent wants to drop the message silently without letting the sender know, it can reject the message with a “successful” response code. Otherwise, it can send back an error response to indicate why the message was blocked. This results in a rejection of the message at the SMTP protocol level; therefore, a DSN does not have to be generated.

For example, the following agent handles the OnEndOfData event, determines whether the message should be blocked and which response to block it with, and then calls a method on the source object to block the message, if necessary.

    public class SampleSmtpReceiveAgent : SmtpReceiveAgent
    {
        private static SmtpResponse silentRejectResponse =
            new SmtpResponse("250", "", "OK");

        private static SmtpResponse normalRejectResponse =
            new SmtpResponse("500", "", "Message rejected");

        SampleSmtpReceiveAgent()
        {
            this.OnEndOfData += new EndOfDataEventHandler(
                this.OnEndOfDataHandler);
        }

        private void OnEndOfDataHandler(
            ReceiveMessageEventSource source,
            EndOfDataEventArgs e)
        {
            if (this.ShouldBlockMessage(e.MailItem))
            {
                source.RejectMessage(
                    this.GetRejectResponse());
            }
        }

        private bool ShouldBlockMessage(MailItem mailItem)
        {
            // TODO: put logic here to decide whether to block 
            // the message.

            return false;
        }

        private SmtpResponse GetRejectResponse()
        {
            bool silentReject = false;

            // TODO: put logic here to decide which response to use.

            return
                silentReject
                ? SampleSmtpReceiveAgent.silentRejectResponse
                : SampleSmtpReceiveAgent.normalRejectResponse;
        }
    }

The agent can drop a recipient from a message by using the EnvelopeRecipientCollection.Remove Method. This method has three overrides. The first two take a single parameter, with a type of EnvelopeRecipient or RoutingAddress, respectively. Each of these methods silently drops the recipient from the message. The third override takes an EnvelopeRecipient, a DsnType, and an SmtpResponse. This override will drop the recipient and then send a DSN back to the sender if one was requested.

For example, the following agent handles the OnSubmittedMessage event and drops a recipient from the message.

    public class SampleRoutingAgent : RoutingAgent
    {
        private static SmtpResponse rejectResponse =
            new SmtpResponse("500", "", "Recipient rejected");

        public SampleRoutingAgent()
        {
            this.OnSubmittedMessage += new SubmittedMessageEventHandler(
                this.OnSubmittedMessageHandler);
        }

        private void OnSubmittedMessageHandler(
            SubmittedMessageEventSource source, 
            QueuedMessageEventArgs e)
        {
            foreach (EnvelopeRecipient recipient in e.MailItem.Recipients)
            {
                if (this.ShouldDropRecipient(e.MailItem, recipient))
                {
                    if (this.ShouldDropSilently())
                    {
                        e.MailItem.Recipients.Remove(recipient);
                    }
                    else
                    {
                        e.MailItem.Recipients.Remove(
                            recipient,
                            DsnType.Failure,
                            SampleRoutingAgent.rejectResponse);
                    }
                }
            }
        }

        private bool ShouldDropRecipient(
            MailItem mailItem,
            EnvelopeRecipient recipient)
        {
            // TODO: put logic here to decide whether to block
            // the recipient.

            return false;
        }

        private bool ShouldDropSilently()
        {
            // TODO: put logic here to decide whether to block
            // silently or send back a DSN.

            return false;
        }
    }

If the agent decides to reject the message, it can do so either by rejecting each recipient, or by calling the QueuedMessageEventSource.Delete Method, which achieves the same thing. Deleting the message in this manner does not generate a DSN back to the sender of the message. This method exists on the event sender of each RoutingAgent event. Deleting a message does not generate a DSN.

For example, the following agent handles the RoutingAgent.OnSubmittedMessage Event and deletes the current message.

    public class SampleRoutingAgent : RoutingAgent
    {
        public SampleRoutingAgent()
        {
            this.OnSubmittedMessage += new SubmittedMessageEventHandler(
                this.OnSubmittedMessageHandler);
        }

        private void OnSubmittedMessageHandler(
            SubmittedMessageEventSource source, 
            QueuedMessageEventArgs e)
        {
            if (this.ShouldDeleteMessage(e.MailItem))
            {
                source.Delete();
            }
        }

        private bool ShouldDeleteMessage(MailItem mailItem)
        {
            // TODO: put logic here to decide whether to block
            // the message.

            return false;
        }
    }