Getting Started with SMTP, POP, & IMAP

IPWorks has components to work with the traditional mail protocols SMTP, POP, and IMAP. The guide below highlights each of these with examples. Working with modern mail REST APIs (Office365, Gmail, etc.) is covered in our guide to Cloud Mail.

Introduction

SMTP sends mail, while IMAP and POP retrieve mail and manage mailboxes. All common authentication methods, as well as SSL/TLS connections, are supported and easily configured. Check out each section below for more.

Authentication
SMTP
IMAP
POP
SSL/TLS

Authentication

Authentication functions identically on all mail components. Set the AuthMechanism property to what the mail server expects. All AuthMechanisms other than amXOAUTH2 require setting User and Password. amXOAUTH2 examples can be found here.

This example will apply when using amUserPassword, amCRAMMD5, amNTLM, amAPOP, amSASLPlain, amSASLDigestMD5, and amKerberos.


Smtp mail = new Smtp();
mail.User = "MyUser";
mail.Password = "MyPassword";
mail.MailServer = "smtp.server.com";
mail.AuthMechanism = SmtpAuthMechanisms.amUserPassword; // Default
mail.Connect();

SMTP

Applicable Components: SMTP FileMailer HtmlMailer

IPWorks has several components for SMTP. The examples below use HtmlMailer and get progressively more advanced. The last example uses the SMTP and MIME components.

Send a Basic Email


Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "A Most Basic Email";
mail.MessageText = "Dear Madam,\n\nThis is just a plaintext message.\n\nRegards,\nJohn";
mail.Send();

Send an HTML Email


Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "A Simple HTML Email";
mail.MessageHTML = "A Title Might Go Here
Followed by some text";
// MessageText will automatically be populated with an equivalent plaintext
// representation of MessageHTML, unless overwritten.
mail.Send();

Embed an Image

There are three ways to embed an image into an HTML email.


// Provide filepath directly to src attribute
Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "An HTML Email with Embedded Image";
mail.MessageHTML = "A Title Might Go Here
Followed by an image:
";
mail.Send();


// Add image and specify cid
Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "An HTML Email with Embedded Image";
mail.ParseHTML = false;
mail.MessageHTML = "A Title Might Go Here
Followed by an image:
";
HTMLImage image = new HTMLImage("C:\\path\\to\\image.jpg");
image.ImageType = "image/jpeg";
image.Id = "1234";
mail.Images.Add(image);
mail.Send();


// Provide base64 data to src attribute
Netcode nc = new Netcode();
nc.DecodedFile = "C:\\path\\to\\image.jpg";
nc.Format = NetcodeFormats.fmtBase64;
nc.Encode();
string base64Image = nc.EncodedData;
Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "An HTML Email with Embedded Image";
mail.Config("ConvertImgData2CID=true");
mail.MessageHTML = "A Title Might Go Here
Followed by an image:
";
mail.Send();

Add an Attachment


Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "A Email with Attachment";
mail.MessageHTML = "A Title Might Go Here
Please read this important attachment.";
mail.AddAttachment("C:\\temp\\test.txt");
mail.Send();

Save Raw Message

It may be beneficial to save the raw message in RFC 822 format. Use the MessageHeadersString and TransferText configiration settings to retrieve the raw message.


Htmlmailer mail = new Htmlmailer();
// ...
mail.Send();
string rawMsg = mail.Config("MessageHeadersString") + mail.Config("TransferText");

Advanced Example using SMTP & MIME

This example uses SMTP and MIME together to send a message with a plaintext part, HTML part, embedded image, and attachment. This combination provides the most control when constructing a message.


// This type of email message is as a "nested" MIME message (i.e. There
// is one MIME message wrapped inside another MIME message).

string imagePath = "C:\\path\\to\\image.jpg";
string imageName = imagePath.Substring(imagePath.LastIndexOf(@"\") + 1);
string attachmentPath = "C:\\path\\to\\attachment.pdf";
string attachmentName = attachmentPath.Substring(attachmentPath.LastIndexOf(@"\") + 1);
string innerMime = "";
string innerMimeHeaders = "";
Mime m = new Mime();

// First the inner message needs to be constructed.  
// It contains the HTML and plaintext portions.
m.ContentType = "multipart/alternative";

m.Parts.Add(new MIMEPart());
m.Parts[0].ContentType = "text/plain";
m.Parts[0].Encoding = MIMEPartEncodings.peQuotedPrintable;
m.Parts[0].DecodedString = "Plaintext message goes here.";

m.Parts.Add(new MIMEPart());
m.Parts[1].ContentType = "text/html";
m.Parts[1].Encoding = MIMEPartEncodings.peQuotedPrintable;
m.Parts[1].DecodedString = "HTML message goes here
";

m.EncodeToString();

// Save the inner part for later
innerMime = m.Message;
innerMimeHeaders = m.MessageHeadersString;

m.Reset();

// Next construct the outer part, which contains the inner 
// part, an inline image, and pdf attachment.
m.ContentType = "multipart/related";

m.Parts.Add(new MIMEPart());
m.Parts[0].DecodedString = innerMime;
m.Parts[0].Encoding = MIMEPartEncodings.peBinary;
m.Parts[0].Headers = innerMimeHeaders;

m.Parts.Add(new MIMEPart());
m.Parts[1].ContentType = "image/jpeg; name='" + imageName + "'";
m.Parts[1].Encoding = MIMEPartEncodings.peBase64;
m.Parts[1].Headers += "Content-Location: " + imageName;
m.Parts[1].DecodedStringB = File.ReadAllBytes(imagePath);

m.Parts.Add(new MIMEPart());
m.Parts[2].ContentType = "application/pdf; name='" + attachmentName + "'";
m.Parts[2].ContentDisposition = "attachment; name='" + attachmentName + "'; filename='" + attachmentName + "'";
m.Parts[2].Encoding = MIMEPartEncodings.peBase64;
m.Parts[2].DecodedStringB = File.ReadAllBytes(attachmentPath);

m.EncodeToString();

// Send the constructed message with Smtp
Smtp mail = new Smtp();
mail.MailServer = "smtp.server.com";
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "An Advanced Email Made with MIME";
mail.OtherHeaders = m.MessageHeadersString;
mail.Message = m.Message;

try
{
  mail.Send();
}
catch (Exception ex) { Console.WriteLine(ex.Message); }

IMAP

Applicable Components: IMAP

Use the IMAP component to retrieve mail and manage mailboxes. To connect to a server, set MailServer and optionally MailPort, then call Connect. This will both connect and begin authentication with the server. Afterwards select a mailbox by setting Mailbox and calling SelectMailbox. Once selected other operations may be performed. Check out the examples below.

Connect to a MailServer


Imap mail = new Imap();
mail.MailServer = "imap.server.com";
mail.User = "user@server.com";
mail.Password = "YourPassword";
mail.Connect();

List Available Mailboxes


Imap mail = new Imap();
mail.OnMailboxList += (obj, ev) => Console.WriteLine(ev.Mailbox);
// ...
mail.ListMailboxes();

Select a Mailbox


Imap mail = new Imap();
// ...
mail.Mailbox = "INBOX";
mail.SelectMailbox();

List all Messages in a Mailbox

To get basic information about all messages in the selected Mailbox, first select all messages with MessageSet. Messages will be numbered 1 through MessageCount. Then call FetchMessageInfo. The MessageInfo event will fire for every selected message and has metadata like Id, Subject, From, and more.


Imap mail = new Imap();
mail.OnMessageInfo += (obj, ev) => Console.WriteLine(ev.Subject + " " + ev.From + " " + ev.MessageDate);
// ...
mail.SelectMailbox();
mail.MessageSet = "1:" + mail.MessageCount;
mail.FetchMessageInfo();

Save Raw Message

It may be beneficial to save the raw message in RFC 822 format. Use FetchMessageHeaders and FetchMessageText to populate MessageHeadersString and MessageText. Combine these into the raw message.


Imap mail = new Imap();
// ...
mail.MessageSet = "1";
mail.FetchMessageHeaders();
mail.FetchMessageText();
Console.WriteLine(mail.MessageHeadersString + mail.MessageText);

Save Attachments

An attachment will be encoded as a single part. First call FetchMessageInfo to populate MessageParts, then iterate over the collection calling FetchMessagePart for any detected attachments. If LocalFile is set to a file name, the part is stored there. Otherwise the contents are stored in MessageText.


Imap mail = new Imap();
// ...
mail.MessageSet = "1";
mail.FetchMessageInfo();
foreach(MessagePart p in mail.MessageParts)
{
  if (p.ContentDisposition.ToLower().Contains("attachment"))
  {
    mail.LocalFile = "C:\\path\\to\\" + p.Filename;
    mail.FetchMessagePart(p.Id);
    //Console.WriteLine(mail.MessageText); // Contains the part if LocalFile=""
  }
}

Delete Messages


Imap mail = new Imap();
// ...
mail.MessageSet = "1:23";
mail.DeleteFromMailbox(); // Marks message(s) with 'Deleted' flag
mail.ExpungeMailbox();    // Removes all messages with 'Deleted' flag

POP

Applicable Components: POP

Use the POP component to retrieve mail. To connect to a server, set MailServer and optionally MailPort, then call Connect. This will both connect and begin authentication with the server. Set MessageNumber to select a message to operate on. Check out the examples below.

Connect to a MailServer


Pop mail = new Pop();
mail.MailServer = "pop.server.com";
mail.User = "user@server.com";
mail.Password = "YourPassword";
mail.Connect();

List all Messages in a Mailbox

To get basic information about all messages in the selected Mailbox, iterate 1 through MessageCount while calling RetrieveHeaders. The Header event will fire for every message header which can be parsed for metadata like Subject, From, Date, and more.


Pop mail = new Pop();
// ... 
string subject, date, from = "";
mail.OnHeader += (obj, ev) =>
{
  switch (ev.Field.ToLower())
  {
    case ("subject"):
      subject = ev.Value;
      break;
    case ("date"):
      date = ev.Value;
      break;
    case ("from"):
      from = ev.Value;
      break;
  }
};
// ...
for(int x = 1; x <= mail.MessageCount; x++)
{
  subject = date = from = "";
  mail.MessageNumber = x;
  mail.RetrieveHeaders();
  Console.WriteLine(subject + " | " + from + " | " + date);
}

Save a Raw Message


Pop mail = new Pop();
// ...
int msgNum = 1;
mail.MessageNumber = msgNum;
mail.Retrieve();
Console.WriteLine(mail.MessageHeadersString + mail.MessageText);

Save a Raw Message To Disk


Pop mail = new Pop();
// ...
int msgNum = 1;
mail.Config("IncludeHeaders=true");
mail.LocalFile = "C:\\path\\to\\raw" + msgNum + ".eml";
mail.MessageNumber = msgNum;
mail.Retrieve();

Delete A Message


Pop mail = new Pop();
// ...
mail.MessageNumber = 1;
mail.Delete();

Using SSL & TLS

Connecting to a secure server over a SSL/TLS connection is easily done: set SSLStartMode and, if needed, MailPort. Each sslStartMode is detailed below.

sslImplicit: SSL/TLS negotations start immediately on a dedicated SSL/TLS port.
sslExplicit: STARTTLS is sent in plaintext to a port that may use both plaintext and SSL/TLS. If the server response indicates SSL/TLS is supported, then negotiations begin.

This example sends mail over an implicit TLS connection. SSLStartMode works exactly the same on all mail components.


Htmlmailer mail = new Htmlmailer();
mail.MailServer = "smtp.server.com";
mail.MailPort = 465;
mail.SSLStartMode = HtmlmailerSSLStartModes.sslImplicit;
mail.SendTo = "recipient@friendly.com";
mail.From = "sender@server.com";
mail.Subject = "A Most Basic Email";
mail.MessageText = "Dear Madam,\n\nThis is just a message.\n\nRegards,\nJohn";
mail.Send();

Below are the official IANA port numbers for SMTP, IMAP, and POP.

	SMTP	IMAP	POP
Plaintext	25	143	110
SSL/TLS	465¹/587²	993	995

¹sslImplicit ²sslExplicit

Your server may use different port numbers.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@nsoftware.com.