Skip to content

Home

Jump to bottom
Norbert Bietsch edited this page Mar 7, 2018 · 20 revisions
Logo

Welcome to the MailMergeLib wiki

MailMergeLib is an SMTP template mail client library written in C# which provides comfortable mail merge capabilities and SMTP fail-over features, as well as replacing {placeholders} in the text with data. All relevant class instances can be saved and restored (Serialization).

Jump Start

Note MailMergeLib has a lot of options for formatting data in {placeholders} and configuring MailMergeMessages and MailMergeSender which are only scratched on the surface in this "Jump Start" section.

Send a single mail message

Create a Data Source

First of all reference the library and create a simple data source. It's content will be used for {placeholders}.

using MailMergeLib;
var variables = new Dictionary<string, string>() { { "Email", "sample@example.com" }, {"Name", "John Specimen"} };

Note Besides Dictionaries many more data types are supported.

Create the Message Subject and Text Body

Next a new message with plain text and HTML body parts. The HTML part is optional; you can create pure text messages as well. Placeholders are the key names of the Dictionary in curly braces.

var mmm = new MailMergeMessage("Personal message for {Name}", 
		"A simple message for {Name}",
		"<html><head><title>No title</title></head><body>A simple message for {Name}</body></html>");

Note Here the plain text was entered while creating the message. It can be derived from the HTML part by calling mmm.ConvertHtmlToPlainText()

Add the Mail Addresses

Of course at least a From and a To mail address must be added. Again, {placeholders} can be used.

mmm.MailMergeAddresses.Add(new MailMergeAddress(MailAddressType.From, "whatever@example.com"));
mmm.MailMergeAddresses.Add(new MailMergeAddress(MailAddressType.To, "{Name}", "{Email}"));

Now we are done with the mail message. Curious how the final mail message will look like? Let's write it to a file and explore it with a text editor or a mail client like Microsoft Outlook.

var mime = mmm.GetMimeMessage(variables);
mime.WriteTo("enter-your-filename-here.eml")
MailMergeMessage.DisposeFileStreams(mime);

Create the Sender

Creating sender for mail messages is as straight forward as with any mail client you are familiar with. With each instance of MailMergeSender a default array of SmtpClientConfigs with one entry will be initialized.

var mms = new MailMergeSender();

mms.Config.MaxNumOfSmtpClients = 1;  // enough for a single email
mms.Config.SmtpClientConfig[0].MessageOutput = MessageOutput.SmtpServer;
mms.Config.SmtpClientConfig[0].SmtpHost = "smtp.mailprovider.net";
mms.Config.SmtpClientConfig[0].SmtpPort = 587;
mms.Config.SmtpClientConfig[0].NetworkCredential = new Credential("username", "password");
mms.Config.SmtpClientConfig[0].MaxFailures = 3; // more throw an exception
// Because the data parameter is an IEnumerable, it must be boxed to an object.
mms.Send(mmm, (object) variables);

or

await mms.SendAsync(mmm, (object) variables);

Send a mail message to a list of recipients

Simply replace the variables part from the sample above with this:

var variables = new[]
{
	new { Email = "sample@example.com", Name = "John Specimen" },
	new { Email = "mary@example.com",   Name = "Mary Specimen" }
};

Then call the IEnumerable overload of the send method:

mms.Send(mmm, variables);

or

await mms.SendAsync(mmm, variables);

Gain: There is much more

Read the docs...

Clone this wiki locally