Tests sending a mail message to the recipients without actual submitting of the message data.

Parameters

failureThreshold

Specifies whether the method should succeed if all recipients succeed, or at least one recipient succeeds (even if other recipients fail).

Return Value

OK if the sender and any or all (depends on failureThreshold value) recipients have been accepted by for delivery; otherwise, one of TestSendResult values specifying the error details.

Remarks

When failureThreshold is Default, failed recipients are always allowed in direct send mode, and can be either disabled or enabled when submitting to SMTP relay server (depending on AllowRefusedRecipients property value). Other values of failureThreshold parameter allow the developer to override the default behavior for both direct send and SMTP relay send modes.

This method can be used prior to actual Send method call in order to make sure the sender and all recipients will be accepted during send mail operation. If any/all recipients fail, the method returns corresponding TestSendResult value. MailBeeException is not thrown. ErrorOccurred event is still raised, so the developer can obtain additional information about the error by handling this event.

TestSend method is especially useful in direct send scenarios (discovering SMTP MX servers via DNS MX lookup rather than using predefined SMTP relay server). When no SMTP relay server is used, it's not possible to send to all recipients without fail, and cancel sending if at least one recipient fails (so that the message would be sent either to all recipients or to nobody). This is because the message may be sent to many SMTP MX servers in direct send mode, and if it was already sent to the first server and fails for the second one, it's not possible to tell the first server to rollback and cancel the recent mail submission. This is different from sending to SMTP relay server, where entire send mail operation is a single transaction. If it's cancelled, no recipients previously submitted will receive the message. When sending to an SMTP relay server, the developer can use AllowRefusedRecipients property to control whether the component should return an error if at least one recipient fails.

Note   The mail message submission may still fail on Send operation even if all recipients and the sender are valid. This typically occurs when the server accepts the sender and the recipients but rejects the message data (for instance, the message is too large, or the server decides the message contains spam or virus). Also, the server might be down at the moment when Send method gets called even if it was fine during TestSend method call.

Example

This sample sends a mail message in direct send mode (no SMTP relay server is used). To make sure all recipients will receive the message, TestSend is called first. Extensive error checking is performed in ErrorOccurred event handler to learn why the error occurred.

[C#]
using System;
using MailBee;
using MailBee.SmtpMail;
using MailBee.DnsMX;
using MailBee.Mime;

class Sample
{
    // ErrorOccurred event handler.
    private static void OnErrorOccurred(object sender, ErrorEventArgs e)
    {
        if (e.Reason is MailBeeSmtpRefusedRecipientException)
        {
            MailBeeSmtpRefusedRecipientException ex =
                e.Reason as MailBeeSmtpRefusedRecipientException;
            Console.WriteLine(ex.RefusedRecipientEmail + " was refused by the server");
        }
        else if (e.Reason is MailBeeDnsNameErrorException)
        {
            MailBeeDnsNameErrorException ex = e.Reason as MailBeeDnsNameErrorException;
            Console.WriteLine(ex.HostName + " is unknown host");
        }
        else if (e.Reason is MailBeeDnsProtocolNegativeResponseException)
        {
            MailBeeDnsProtocolNegativeResponseException ex =
                e.Reason as MailBeeDnsProtocolNegativeResponseException;
            Console.WriteLine("DNS server returned error for " + ex.HostName);
        }
        else if (e.Reason is MailBeeConnectionException)
        {
            MailBeeConnectionException ex = e.Reason as MailBeeConnectionException;
            if (ex.Protocol == TopLevelProtocolType.Smtp)
            {
                Console.WriteLine("Connection problem with " +
                    ex.RemoteHostName + " SMTP MX server ");
            }
        }
        else
        {
            Console.WriteLine(e.Reason.Message);
        }
    }

    // The actual code.
    static void Main(string[] args)
    {
        Smtp mailer = new Smtp();

        // Get DNS servers list from OS settings or config file 
        // (like app.config).
        mailer.DnsServers.Autodetect();

        mailer.From.AsString = "John Doe <jdoe@domain.com>";

        // Specify recipients.
        mailer.To.AsString = "no-display-name@website.com, \"Bill Smith, Jr.\" &lt;bill.smith@company.com&gt;";
        mailer.To.AddFromString("Kathy Smith &lt;k.smith@domain.com&gt;");
        mailer.To.AddFromString("email@address.com");
        mailer.To.Add("Mike Jackson, Sales Manager", "mj@company.com", "Sales Department");

        mailer.Subject = "Newsletter";
        mailer.BodyPlainText = "This is our weekly newsletter.";

        // Subscribe to the ErrorOccurred event.
        mailer.ErrorOccurred += new ErrorEventHandler(OnErrorOccurred);

        // Make sure all the recipients are ok.
        if (mailer.TestSend(SendFailureThreshold.AllRecipientsFailed) != TestSendResult.OK)
        {
            Console.WriteLine("No recipients can receive the message.");
        }
        else if (mailer.GetRefusedRecipients().Count > 0)
        {
            Console.WriteLine("The following recipients failed: " +
                mailer.GetRefusedRecipients().ToString());
        }
        else
        {
            Console.WriteLine("All recipients are ok. Will send the message now.");
            mailer.Send();
            Console.WriteLine("Sent to: " + mailer.GetAcceptedRecipients().ToString());
        }
    }
}

[Visual Basic]
Imports System
Imports MailBee
Imports MailBee.SmtpMail
Imports MailBee.DnsMX
Imports MailBee.Mime

Class Sample
    ' ErrorOccurred event handler.
    Private Shared Sub OnErrorOccurred(ByVal sender As Object, ByVal e As ErrorEventArgs)
        If (TypeOf e.Reason Is MailBeeSmtpRefusedRecipientException) Then
            Dim ex As MailBeeSmtpRefusedRecipientException = e.Reason
            Console.WriteLine(ex.RefusedRecipientEmail & " was refused by the server")
        ElseIf (TypeOf e.Reason Is MailBeeDnsNameErrorException) Then
            Dim ex As MailBeeDnsNameErrorException = e.Reason
            Console.WriteLine(ex.HostName & " is unknown host")
        ElseIf (TypeOf e.Reason Is MailBeeDnsProtocolNegativeResponseException) Then
            Dim ex As MailBeeDnsProtocolNegativeResponseException = e.Reason
            Console.WriteLine("DNS server returned error for " + ex.HostName)
        ElseIf (TypeOf e.Reason Is MailBeeConnectionException) Then
            Dim ex As MailBeeConnectionException = e.Reason
            If (ex.Protocol = TopLevelProtocolType.Smtp) Then
                Console.WriteLine("Connection problem with " & _
                    ex.RemoteHostName & " SMTP MX server ")
            End If
        Else
            Console.WriteLine(e.Reason.Message)
        End If
    End Sub

    ' The actual code.
    Shared Sub Main(ByVal args As String())
        Dim mailer As New Smtp

        ' Get DNS servers list from OS settings or config file 
        ' (like app.config).
        mailer.DnsServers.Autodetect()

        mailer.From.AsString = "John Doe <jdoe@domain.com>"

        ' Specify recipients.
        mailer.To.AsString = "no-display-name@website.com, ""Bill Smith, Jr."" <bill.smith@company.com>"
        mailer.To.AddFromString("Kathy Smith <k.smith@domain.com>")
        mailer.To.AddFromString("email@address.com")
        mailer.To.Add("Mike Jackson, Sales Manager", "mj@company.com", "Sales Department")

        mailer.Subject = "Newsletter"
        mailer.BodyPlainText = "This is our weekly newsletter."

        ' Subscribe to the ErrorOccurred event.
        AddHandler mailer.ErrorOccurred, AddressOf OnErrorOccurred

        ' Make sure all the recipients are ok.
        If (mailer.TestSend(SendFailureThreshold.AllRecipientsFailed) <> TestSendResult.OK) Then
            Console.WriteLine("No recipients can receive the message.")
        ElseIf (mailer.GetRefusedRecipients().Count > 0) Then
            Console.WriteLine("The following recipients failed: " & _
                mailer.GetRefusedRecipients().ToString())
        Else
            Console.WriteLine("All recipients are ok. Will send the message now.")
            mailer.Send()
            Console.WriteLine("Sent to: " & mailer.GetAcceptedRecipients().ToString())
        End If
    End Sub
End Class

See Also

Smtp Class | MailBee.SmtpMail Namespace

---