EmailMessage

the content of your email is described as an EmailMessage object, this object contains the following data:

• From: the email address to be used as the sender.
• To: the email addresses to be used as the recipients.
• ReplayTo: the reply-to email addresses.
• Bcc: blind carbon copy email addresses.
• Cc: the carbon copy email addresses.
• Subject: the email subject.
• Charset: the optional character set for your message.
• PlainTextContent: the email plain text content.
• HtmlContent: the email HTML content.
• Attachments: the list of attachments.
• Priority: the priority of this email message.
• Headers: Custom headers to be sent with this email message.
• ChannelData: Custom data to be passed to the channel used for sending the email.

how to compose a message?

a message is composed using a factory class called EmailMessageComposer, you get an instance of the factory using the .Compose() method on the Message class

var messageComposer = EmailMessage.Compose();

here is an example of using the fluent syntax to compose a message:

var message = EmailMessage.Compose()
    .To("[email protected]")
    .WithSubject("test email")
    .WithPlainTextContent("this is a test email")
    .WithHtmlContent("<p>this is a test email</p>")
    .WithHighPriority()
    .Build();

you must call Build() at the end to get the Message instance.
now let's have a look at the methods that we can use on the MessageComposer factory to compose a message.

EmailMessageComposer methods

From():

use From() to add a sender.
there are two overloads to this method,

• From(string emailAddress, string displayName = ""): this one allows you to add a sender email with an email address & optional display name.
• From(MailAddress mailAddress): if you already have a System.Net.Mail.MailAddress object you can pass that as the sender.

// add a sender
messageComposer.From("[email protected]");

// add a sender with a display name
messageComposer.From("[email protected]", "sender name");

// add a sender using MailAddress object the with a display name, (the sender display name is optional)
var sender = System.Net.Mail.MailAddress("[email protected]", "sender name");
messageComposer.From(sender);

To():

use To() to add one or more recipients.
there are two overloads to this method,

• To(string emailAddress, string displayName = "", char delimiter = ';'): this overload allows you to add one or more recipients, if you add one recipient you can add a display name, but if you add multiple emails the display name is ignored, the delimiter allows you to specify the delimiter used to split the emails by default is set to ';'.
• To(params MailAddress[] mailAddress): add one or multiple recipients from an array of System.Net.Mail.MailAddress objects.

// add one recipient
messageComposer.To("[email protected]");

// add one recipient with a display name
messageComposer.To("[email protected]", "recipient name");

// add multiple recipient with default delimiter
messageComposer.To("[email protected]; [email protected]; [email protected]");

// add multiple recipient with custom delimiter
messageComposer.To("[email protected], [email protected], [email protected]", delimiter: ',');

// add one recipient using MailAddress object with a display name, (the sender display name is optional)
var recipient = System.Net.Mail.MailAddress("[email protected]", "recipient name");
messageComposer.To(recipient);

// add multiple recipients using MailAddress object with a display name
var recipients = new[] {
    System.Net.Mail.MailAddress("[email protected]", "recipient1 name"),
    System.Net.Mail.MailAddress("[email protected]", "recipient2 name"),
    System.Net.Mail.MailAddress("[email protected]", "recipient3 name"),
};
messageComposer.To(recipients);

ReplyTo():

use ReplyTo() to add one or more ReplyTo emails.
there are two overloads to this method,

• ReplyTo(string emailAddress, string displayName = "", char delimiter = ';'): this overload allows you to add one or more ReplyTo emails if you add one ReplyTo you can add a display name, but if you add multiple emails the display name is ignored, the delimiter allows you to specify the delimiter used to split the emails by default is set to ';'.
• ReplyTo(params MailAddress[] mailAddress): add one or multiple ReplyTo from an array of System.Net.Mail.MailAddress objects.

// add one replyTo
messageComposer.ReplyTo("[email protected]");

// add one replyTo with a display name
messageComposer.ReplyTo("[email protected]", "replyTo name");

// add multiple replyTo with default delimiter
messageComposer.ReplyTo("[email protected]; [email protected]; [email protected]");

// add multiple replyTo with custom delimiter
messageComposer.ReplyTo("[email protected], [email protected], [email protected]", delimiter: ',');

// add one replyTo using MailAddress object with a display name, (the sender display name is optional)
var replyTo = System.Net.Mail.MailAddress("[email protected]", "replyTo name");
messageComposer.ReplyTo(replyTo);

// add multiple replyTo using MailAddress object with a display name
var replyTos = new[] {
    System.Net.Mail.MailAddress("[email protected]", "replyTo1 name"),
    System.Net.Mail.MailAddress("[email protected]", "replyTo2 name"),
    System.Net.Mail.MailAddress("[email protected]", "replyTo3 name"),
};
messageComposer.ReplyTo(replyTos);

WithBcc() & WithCc():

use WithBcc() and WithCc() to add blind carbon copy and carbon copy emails.

if you noticed ReplyTo() has the same overloads as To(), now the same is applied for both WithBcc() and WithCc(), they have the same overloads and signature, and everything that applies to ReplyTo() and To() is the same for WithBcc() and WithCc().

WithHeader():

WithHeader() is used to attach custom key-value headers to the email message.
there are two overloads to this method,

• WithHeader(string key, string value): add one key-value header.
• WithHeaders(IEnumerable<KeyValuePair<string, string>> headers): add multiple key-value headers.

// add one header
messageComposer.WithHeader("key", "value");

// add multiple headers 
var headers = new new Dictionary<string, string>()
{
    { "key1", "value1" },
    { "key2", "value2" },
    { "key3", "value3" },
};
messageComposer.WithHeaders(headers);

WithHighPriority(), WithLowPriority() and WithNormalPriority():

you can use this function to set the priority of the emails.

IncludeAttachment():

you can use this method to include attachments to the email message, this function accepts a list of the attachments.

• IncludeAttachment(params Email.NET.Attachment[] attachments): add one or more attachment.

we should note that the Email.NET.Attachment is an abstract type, and the types you should use are:

• ByteArrayAttachment(string fileName, byte[] file): to define an attachment from a byte[].
• Base64Attachement(string fileName, string base64): to define an attachment from a base64 string.
• FilePathAttachment(string filePath): to define an attachment from a file path.

// add a byte array file
byte[] byteArrayFileData = GetByteArrayFileData();
messageComposer.IncludeAttachment(new ByteArrayAttachment("file_name.txt", byteArrayFileData));

// add a base64 file
string base64FileData = GetBase64FileData();
messageComposer.IncludeAttachment(new Base64Attachement("file_name.txt", base64FileData));

// add a file
messageComposer.IncludeAttachment(new FilePathAttachment(@"C:\file_name.txt"));

// add multiple files
messageComposer.IncludeAttachment(new Email.NET.Attachment[]
{
    new FilePathAttachment(@"C:\file_name.txt"),
    new Base64Attachement("file_name.txt", base64FileData),
    new ByteArrayAttachment("file_name.txt", byteArrayFileData),
});

PassChannelData():

this method is used to pass custom data to the underlying channel that is used to send the emails.

• PassChannelData(string key, object value): add one channeldata.
• PassChannelData(params Email.NET.Channel.ChannelData[] data): add multiple channel data.

//Add one channel data from a key value
messageComposer.PassChannelData("server_id", 12554);

//Add one channel data from a ChannelData object
messageComposer.PassChannelData(new ChannelData("server_id", 12554));

// add multiple channel data
messageComposer.PassChannelData(new []
{
    new ChannelData("server_id", 12554),
    new ChannelData("api_key", "KEY_DLMSO54S55236SAFCDVK"),
});

instead of passing the data as key-value, each channel will have extension methods that allow you to pass custom configuration, so make sure to check each channel if they have any custom data that you can use to customize the execution behavior of the channel.

Build():

after finishing composing your email you call Build() to build the message instance.

// Build the message instance
Message message = messageComposer.Build();