Puts a "mail merge over database" job onto waiting list for subsequent processing in bulk mode.

Parameters

tag

Any string the developer wants to assign to Tag property of SendMailJob object created by this method. The developer can leave it a null reference (Nothing in Visual Basic).

senderEmailPattern

The e-mail address template of the sender. If it's a null reference (Nothing in Visual Basic), the e-mail address template will be taken from From property.

recipientsPattern

The e-mail address template of the recipients list. If it's a null reference (Nothing in Visual Basic), the recipients list will be constructed via merge of To, Cc, and Bcc patterns with actual values from the data source.

mergeTable

The data source for mail merge.

Remarks

This method allows the application to schedule mail merge over database for subsequent processing with SendJobs, BeginSendJobs, or SubmitJobsToPickupFolder method.

Note   To perform mail merge immediately rather than schedule it, use SendMailMerge method.

The mail merge requirements:

• The template of e-mail to be merged with mergeTable data must be specified in Message property. Normally, Message property specifies the e-mail message to be sent out by Smtp object. In the case of mail merge, this e-mail message is considered as a template where ##Column_Name## patterns will be replaced with the actual data from database table rows during the mail merge process.
• Smtp.DeliveryNotification.TrackingID may also contain a pattern if desired. Thus, it's possible to automatically assign unique tracking ID to the each message sent during mail merge and then receive this ID with bounced messages.
• mergeTable must be the data source containing all the data rows for which e-mails should be generated and sent; typically, this data source is a result of SQL query.
• Names of columns of mergeTable must match pattern names in the e-mail template. For instance, if there is Email column in the data table and the developer wishes to make values from this column appear in resulting e-mails, then the e-mail template must contain ##Email## string in the places where the e-mail address needs to be placed. Patterns are case-sensitive! For instance, if data table column name is Email, only ##Email## pattern will be replaced with the column value. ##email## and ##EMAIL## patterns will be left intact.
• senderEmailPattern can be left null. However, if resulting e-mails should actually be sent from another e-mail address (for instance, resulting e-mails have newsletter@domain.com in "From:" field while you wish to send them from "bounces@domain.com"), then it's required to specify senderEmailPattern. It can contain a pattern (e.g. ##Something##) or refer to the actual value (e.g. from@company.com).
• recipientsPattern have the same meaning for specifying the actual recipients as senderEmailPattern - for the actual sender. For instance, to set the pattern which will take the 1st recipient's e-mail address from Email field of the data table while the 2nd recipient's email address is hard-coded, pass the following as recipientsPattern value: new EmailAddressCollection("##Email##, archive-copy@company.com").
• Setting tag to non-empty value helps to distinguish the current mail merge from other jobs if there are any. This is useful if the application submits and processes multiple jobs and the developer wants to track processing of each job separately. Jobs tags also appear in the log if logging is enabled.

Calling this overload is equivalent to calling AddJob with mergeRowIndices set to null, keepProducedJobs set to true, and keepMergedData set to false.

Exceptions

Example

This console sample sends out 2 newsletters based on the same database table and different e-mail templates. Both newsletters are sent out from the same sender to the same recipients. The first newsletter is more complex and may contain attachments. The second newsletter is simpler.

[C#]
using System;
using System.Data;
using System.Data.OleDb;
using MailBee;
using MailBee.Mime;
using MailBee.SmtpMail;

class Sample
{
    // Occurs when an e-mail message is ready to be sent.
    static void mailer_SendingMessage(object sender, SmtpSendingMessageEventArgs e)
    {
        // Display e-mail address of the e-mail to be sent.
        Console.WriteLine(e.MergeTable.Rows[e.MergeRowIndex]["Email"] + " of '" + e.Tag + "'");

        // You can also subscribe to events like MergingMessage, MessageSent, MessageNotSent
        // to keep the detailed track of mail merge progress.
    }

    static void Main(string[] args)
    {
        Smtp mailer = new Smtp();

        // Logging into a file is useful for troubleshooting.
        mailer.Log.Filename = @"C:\log.txt";
        mailer.Log.Enabled = true;
        mailer.Log.Format = LogFormatOptions.AddContextInfo;
        mailer.Log.Clear();

        // Uncomment the line below to use unlimited number of worker threads (up to 60)
        // and increase performance. Note that not all SMTP servers support this.

        // mailer.MaxThreadCount = -1;

        // Subscribe to event to track send bulk mail progress.
        mailer.SendingMessage += new SmtpSendingMessageEventHandler(mailer_SendingMessage);

        // Setup SMTP server parameters.
        mailer.SmtpServers.Add("mail.domain.com", "jdoe", "secret");

        // Setup e-mail message header template for mail merge.
        mailer.Message.From.AsString = "John Doe <john.doe@domain.com>";
        mailer.Message.To.AsString = "##Name## <##Email##>";
        mailer.Message.Subject = "Our newsletter";

        // Setup DSN template for mail merge. In particular, this can be useful
        // to track bounced messages which may come back from some addresses after
        // sending bulk mail out. If the SMTP server does not support DSN, this
        // setting will be ignored.
        mailer.DeliveryNotification.TrackingID = "##ID##-N";

        // Setup HTML body template.
        mailer.Message.BodyHtmlText = "<html>##Body##</html>";

        // Setup template for adding file attachments upon the specified path.
        // In this sample, the path to attachment files will be constructed as
        // "C:\" + DatabaseRecordField("Doc_path").
        mailer.Message.Merge.AddAttachmentPattern(@"C:\##Doc_path##");

        // Make outgoing e-mails UTF-8 to allow content in any language.
        mailer.Message.Charset = "UTF-8";

        // Tell MailBee to generate alternative plain-text version
        // of each e-mail automatically.
        mailer.Message.Builder.HtmlToPlainMode = HtmlToPlainAutoConvert.IfHtml;

        // Specify database connection string (it may be different in your case).
        string connParams = @"Provider=Microsoft.Jet.OLEDB.4.0; Data Source=C:\Newsletter.mdb;";

        DataTable table = new DataTable();

        // Connect to the database and populate mail merge job to-do list with
        // the data from "mailing_list" table.
        using (OleDbConnection conn = new OleDbConnection(connParams))
        {
            // Open the connection and get the data.
            OleDbCommand command = new OleDbCommand("SELECT * FROM mailing_list", conn);
            conn.Open();
            OleDbDataAdapter adapter = new OleDbDataAdapter();
            adapter.SelectCommand = command;
            adapter.Fill(table);

            // Create a job which is the following task for MailBee: perform mail merge
            // of a newsletter template with data rows of the specified data table and
            // send out each resulting e-mail to its intended recipients.
            mailer.AddJob("Newsletter #1", null, null, table);

            // Change template parameters for another newsletter.
            mailer.Message.Subject = "Newsletter update";

            // Setup DSN template for mail merge. In particular, this can be useful
            // to track bounced messages which may come back from some addresses after
            // sending bulk mail out. If the SMTP server does not support DSN, this
            // setting will be ignored.
            mailer.DeliveryNotification.TrackingID = "##ID##-NU";

            // Setup HTML body template.
            mailer.Message.BodyHtmlText = "<html>Please disregard the newsletter you just received.</html>";

            // If we do not want attachments in second newsletter, remove the pattern.
            mailer.Message.Merge.ClearAttachmentPatterns();

            // Create a job of sending another newsletter to the same recipients.
            mailer.AddJob("Newsletter #2", null, null, table);
        }

        // Run the jobs. The actual mail merge takes place here.
        mailer.SendJobs();
        Console.WriteLine();

        // Report results (row indices in the data table) to the console.
        if (mailer.JobsFailed.Count == 0)
        {
            Console.WriteLine("Both newsletters have been sent out without any errors.");
        }
        else
        {
            if (mailer.JobsSuccessful.Count == 0)
            {
                Console.WriteLine("All newsletter e-mails failed to be sent.");
            }
            else
            {
                Console.WriteLine("Not all newsletter e-mails have been sent.");
                Console.WriteLine();

                Console.WriteLine("Successful rows (Our newsletter): ");
                Console.WriteLine(mailer.JobsSuccessful.GetIndicesAsString(table, "Newsletter #1"));
                Console.WriteLine();

                Console.WriteLine("Failed rows (Our newsletter): ");
                Console.WriteLine(mailer.JobsFailed.GetIndicesAsString(table, "Newsletter #1"));
                Console.WriteLine();

                Console.WriteLine("Successful rows (Newsletter update): ");
                Console.WriteLine(mailer.JobsSuccessful.GetIndicesAsString(table, "Newsletter #2"));
                Console.WriteLine();

                Console.WriteLine("Failed rows (Newsletter update): ");
                Console.WriteLine(mailer.JobsFailed.GetIndicesAsString(table, "Newsletter #2"));
            }
        }
    }
}

[Visual Basic]
Imports System
Imports System.Data
Imports System.Data.OleDb
Imports MailBee
Imports MailBee.Mime
Imports MailBee.SmtpMail

Class Sample
    ' Occurs when an e-mail message is ready to be sent.
    Shared Sub mailer_SendingMessage(ByVal sender As Object, ByVal e As SmtpSendingMessageEventArgs)
        ' Display e-mail address of the e-mail to be sent.
        Console.WriteLine(e.MergeTable.Rows(e.MergeRowIndex)("Email") & " of '" & e.Tag & "'")

        ' You can also subscribe to events like MergingMessage, MessageSent, MessageNotSent
        ' to keep the detailed track of mail merge progress.
    End Sub

    Shared Sub Main(ByVal args() As String)
        Dim mailer As Smtp = New Smtp

        ' Logging into a file is useful for troubleshooting.
        mailer.Log.Filename = "C:\log.txt"
        mailer.Log.Enabled = True
        mailer.Log.Format = LogFormatOptions.AddContextInfo
        mailer.Log.Clear()

        ' Uncomment the line below to use unlimited number of worker threads (up to 60)
        ' and increase performance. Note that not all SMTP servers support this.

        ' mailer.MaxThreadCount = -1;

        ' Subscribe to event to track send bulk mail progress.
        AddHandler mailer.SendingMessage, AddressOf mailer_SendingMessage

        ' Setup SMTP server parameters.
        mailer.SmtpServers.Add("mail.domain.com", "jdoe", "secret")

        ' Setup e-mail message header template for mail merge.
        mailer.Message.From.AsString = "John Doe <john.doe@domain.com>"
        mailer.Message.To.AsString = "##Name## <##Email##>"
        mailer.Message.Subject = "Our newsletter"

        ' Setup DSN template for mail merge. In particular, this can be useful
        ' to track bounced messages which may come back from some addresses after
        ' sending bulk mail out. If the SMTP server does not support DSN, this
        ' setting will be ignored.
        mailer.DeliveryNotification.TrackingID = "##ID##-N"

        ' Setup HTML body template.
        mailer.Message.BodyHtmlText = "<html>##Body##</html>"

        ' Setup template for adding file attachments upon the specified path.
        ' In this sample, the path to attachment files will be constructed as
        ' "C:\" + DatabaseRecordField("Doc_path").
        mailer.Message.Merge.AddAttachmentPattern("C:\##Doc_path##")

        ' Make outgoing e-mails UTF-8 to allow content in any language.
        mailer.Message.Charset = "UTF-8"

        ' Tell MailBee to generate alternative plain-text version
        ' of each e-mail automatically.
        mailer.Message.Builder.HtmlToPlainMode = HtmlToPlainAutoConvert.IfHtml

        ' Specify database connection string (it may be different in your case).
        Dim connParams As String = "Provider=Microsoft.Jet.OLEDB.4.0; Data Source=C:\Newsletter.mdb;"

        Dim table As DataTable = New DataTable

        ' Connect to the database and populate mail merge job to-do list with
        ' the data from "mailing_list" table.
        Dim conn As OleDbConnection
        Try
            conn = New OleDbConnection(connParams)
            ' Open the connection and get the data.
            Dim command As OleDbCommand = New OleDbCommand("SELECT * FROM mailing_list", conn)
            conn.Open()
            Dim adapter As OleDbDataAdapter = New OleDbDataAdapter
            adapter.SelectCommand = command
            adapter.Fill(table)

            ' Create a job which is the following task for MailBee: perform mail merge
            ' of a newsletter template with data rows of the specified data table and
            ' send out each resulting e-mail to its intended recipients.
            mailer.AddJob("Newsletter #1", Nothing, Nothing, table)

            ' Change template parameters for another newsletter.
            mailer.Message.Subject = "Newsletter update"

            ' Setup DSN template for mail merge. In particular, this can be useful
            ' to track bounced messages which may come back from some addresses after
            ' sending bulk mail out. If the SMTP server does not support DSN, this
            ' setting will be ignored.
            mailer.DeliveryNotification.TrackingID = "##ID##-NU"

            ' Setup HTML body template.
            mailer.Message.BodyHtmlText = "<html>Please disregard the newsletter you just received.</html>"

            ' If we do not want attachments in second newsletter, remove the pattern.
            mailer.Message.Merge.ClearAttachmentPatterns()

            ' Create a job of sending another newsletter to the same recipients.
            mailer.AddJob("Newsletter #2", Nothing, Nothing, table)

        Finally
            If Not conn Is Nothing Then
                conn.Close()
            End If
        End Try

        ' Run the jobs. The actual mail merge takes place here.
        mailer.SendJobs()
        Console.WriteLine()

        ' Report results (row indices in the data table) to the console.
        If mailer.JobsFailed.Count = 0 Then
            Console.WriteLine("Both newsletters have been sent out without any errors.")
        Else
            If mailer.JobsSuccessful.Count = 0 Then
                Console.WriteLine("All newsletter e-mails failed to be sent.")
            Else
                Console.WriteLine("Not all newsletter e-mails have been sent.")
                Console.WriteLine()

                Console.WriteLine("Successful rows (Our newsletter): ")
                Console.WriteLine(mailer.JobsSuccessful.GetIndicesAsString(table, "Newsletter #1"))
                Console.WriteLine()

                Console.WriteLine("Failed rows (Our newsletter): ")
                Console.WriteLine(mailer.JobsFailed.GetIndicesAsString(table, "Newsletter #1"))
                Console.WriteLine()

                Console.WriteLine("Successful rows (Newsletter update): ")
                Console.WriteLine(mailer.JobsSuccessful.GetIndicesAsString(table, "Newsletter #2"))
                Console.WriteLine()

                Console.WriteLine("Failed rows (Newsletter update): ")
                Console.WriteLine(mailer.JobsFailed.GetIndicesAsString(table, "Newsletter #2"))
            End If
        End If
    End Sub
End Class

See Also

Smtp Class | MailBee.SmtpMail Namespace | Smtp.AddJob Overload List | RetryFailedJobs | SendMailMerge

---