Topiqs  
Users : 1081 Topiqs : 626
Create New Topiq
Home
Find Friends
Sign in
Tools
Tabify
Email
Name

Sending Email in ASP.NET Core 3  7 

Page
Page Profile Picture
Webmodelling
Category
Creator
Profile Picture
Inspect
Stats
Created Urls Favourites Opened Upvotes Comments
3. Dec 2019 7 0 731 0 0

This tutorial is a step-by-step demo how to send emails in ASP.NET Core using Gmail SMTP for development & hMailServer for production.

 

Index :

Appendixes :

 

 

 

Introduction

This tutorial will demo sending email from ASP.NET Core both on your development machine and on your production machine - the ASP.NET Core code is the same, but the SMTP servers are different :

 

SMTP servers used :

  • Gmail SMTP : for Development Machine. Gmail free SMTP server is limited to 50 emails per day - so it cannot be used for production, however as it is free, reliable and easy to use, it is perfect for development.
  • hMailServer : for Production Machine. hMailServer on the other hand is a both free, battle tested, open source & unrestricted email server with a huge community - if your production machine is a Windows server, hMailServer is likely your best bet.

Here is a diagram of what I will build  in this tutorial : 

 

Note that there are 2 good reasons to NOT use hMailServer on our development machine :

  • The real reason is that we can generally NOT setup public PTR records pointing to our development machine and would for that reason never be able to send emails to any account on gmail nor accounts on many other email servers.
  • However another reason is that then we troubleshoot problems in development, we would like to feel confident that the SMTP server is working and correctly configured - this is nearly guaranteed if we use the Gmail SMTP server.

 

 

 

Creating the ASP.NET Core App

Instead of only showing the email sending code, in this tutorial I will build a fresh new ASP.NET Core 3.0 App to showcase everything that is necessary to get ASP.NET Core emailing going.

 

 

Creating the ASP.NET Core Visual Studio project

First let's create the Visual Studio project and the folders & files that will become our ASP.NET Core App : (we will create a minimum ASP.NET Core MVC project)

  1. Open Visual Studio (here VS 16.3.9).
  2. Create a new project.
  3. Select project type here ASP.NET Core Web Application .
    Note that if you use an earlier major version of Visual Studio (like 15.x), your screen will differ and this step will include both name & location. Also note that my VS 16.3.9 have only a few components loaded - you may see a lot more possibilities than on this screenshot.
  4. Name & Location. Here the name of course Email, while the location will depend on your personal setup.
  5. Use the Empty template and select ASP.NET Core version 3.0 if you have it (if you don't have version 3.0, just select an earlier version, only an insignificant part of this tutorial not related to the email sending code depends on version 3.0).
  6. Email project created - even if we selected the Empty project template some essential files have already been created : (for the first time VS in version 16.x have a truly empty template, but I like the standard empty template in 16.x which is equal to empty template in 15.x)
    1. appsettings.json : we will add config settings for hMailServer to this file.
    2. appsettings.development.json : we will add config settings for Gmail SMTP to this file.
    3. Program.cs : this file don't need to be edited in this project.
    4. Startup.cs : we will edit this file.
  7. Create 5folders for file organization
    1. Add a Controllers folder under the Email project
      1. In Solution Explorer right click the "Email" project node, select "Add" and then "New Folder".
      2. Change the "NewFolder" name to "Controllers".
    2. Add a Views folder under the "Email" project
    3. Add a Home folder under the "Views" folder
    4. Add a Shared folder under the "Views" folder
    5. Add a Services folder under the "Email" project
  8. Create 6 files : (additional to the 4 default created files)
    1. Add a HomeController.cs  controller class file in the "Controllers" folder
      1. In Solution Explorer right click the "Controllers" folder, select Add and then "New Item".
      2. Select Controller Class type and be sure the name is HomeController.cs and press the Add button.
      3. HomeController.cs created.
    2. Add an Index.cshtml Razor View file in the "Views\Home" folder
    3. Add a _Layout.cshtml Razor View file in the "Views\Shared" folder
    4. Add a _ViewStart.cshtml Razor View file in the "Views" folder
    5. Add an EmailSender.cs class file in the "Services" folder
    6. Add an IEmailSender.cs interface file in the "Services" folder
  9. Press ctrl+F5 to open the project - be sure you get the Hello World web page (if you get a notification regarding SSL or another problem, please read the official Get started with ASP.NET Core MVC for 3.0)

 

Adding MailKit NuGet package to project

Sending emails is a core functionality of most web applications and yet ASP.NET Core does NOT come with a proper SmtpClient - the official System.Net.Mail.SmtpClient is obsolete.

 

Microsoft recommends using MailKit (which I admit is the only reason I call it the best)

Luckily some people have created a modern SmtpClient called MailKit, MailKit.Net.Smtp.SmtpClient, recommended by Microsoft and with a lot of StackOverflow activity - this tutorial will use MailKit.

 

Ok, lets add MailKit to the Email project :

  1. In solution explorer right click on "Dependencies"
  2. Search for the MailKit package
    1. Be sure "Browse" is selected at the top.
    2. Write mailkit in the search field and click enter.
  3. Select the NETCore.MailKit package in the left pane and click Install in the right pane.
  4. In the "Preview Changes" popup click the Ok button.
  5. In the "License Acceptance" popup click the "I Accept" button.
  6. MailKit installed.

 

 

Setting up Gmail SMTP for development purpose

Gmail SMTP is perfect for development purposes not least because smtp servers provided by a hosting company typically does NOT allow you to send emails from your development machine (typically they only allows relaying emails sent from the host machine).

 

However before you can use Gmail SMTP a few things have to be done :

  1. Be sure you have a gmail account like my-name@gmail.com : most people have but if you don't then go to https://gmail.com and create an account.
  2. Turn on "Less Secure Apps"
    1. Go to https://myaccount.google.com/lesssecureapps
    2. Be sure the "Allow less secure apps" is ON

Ok, that is all what is needed, below we will use your gmail account (email address & password) to send email from a C# SmtpClient to any email address through the Gmail SmtpServer.

 

 

 

Coding the ASP.NET Core Email App

With the project, the folders & the code files created and the MailKit package added, we are ready to actual do some coding.

 

In Visual Studio open the Startup.cs file and change it to the following code : (this Startup.cs is for using ASP.NET Core 3.0, however I have supplied out-commented code for earlier versions)

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
 
using Email.Services;
 
namespace Email
{
   public class Startup
   {
       /* BEFORE VERSION 3.0 START */
       // private static IConfiguration Configuration;
 
       // public Startup(IHostingEnvironment env)
       // {
       //        var configBuilder = new ConfigurationBuilder()
       //          .SetBasePath(env.ContentRootPath)
       //          .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
       //          .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true)
 
       //        Configuration = configBuilder.Build();
       // }
       /* BEFORE VERSION 3.0 END */
 
       public void ConfigureServices(IServiceCollection services)
       {
           /* BEFORE VERSION 3.0 START */
           // services.AddMvc(); // if using version earlier than 2.2
           // services.AddMvc(options => { options.EnableEndpointRouting = false; }); // if using version 2.2
 
           // services.AddSingleton<IConfiguration>(Configuration);
           /* BEFORE VERSION 3.0 END */
 
           /* VERSION 3.0 START */
           services.AddControllersWithViews();
           /* VERSION 3.0 END */
 
           services.AddScoped<IEmailSender, EmailSender>(); // no matter what version
       }
 
       public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
       {
           /* BEFORE VERSION 3.0 START */
           // app.UseMvcWithDefaultRoute()
           /* BEFORE VERSION 3.0 END */
 
           /* VERSION 3.0 START */
           app.UseRouting();
 
           app.UseEndpoints(endpoints =>
           {
               endpoints.MapControllerRoute(
                   name: "default",
                   pattern: "{controller=Home}/{action=Index}/{id?}");
           });
           /* VERSION 3.0 END */
       }
   }
}

 

In the Startup.cs code you can see that if we use an earlier version than ASP.NET Core 3.0 we will typically write a lot of code to setup configuration and add the Configuration object to DI, while in version 3.0 we not only do not need to write code outselves to setup the Configuration object, we also don't need to add it to DI (both is default done in Program.cs).

 

However, with the Configuration object setup, it gives meaning to add the configuration values to appsettings, in this section we only add the development configuration, so open the appsettings.development.json file and fill in the Gmail SMTP connection details using your own email address and password :

 

{
    "Email": {
        "SmtpServer": "smtp.gmail.com",
        "SmtpPort": "465",
        "SmtpUsername": "yourGmailName@gmail.com",
        "SmtpPassword": "yourGmailPassword",
        "FromAddress": "yourGmailName@gmail.com",
        "EnableSsl": "true",
        "UseDefaultCredentials": "false"
    }
}

 

 

Open the IEmailSender.cs file and add the Send interface member. Be sure it looks like this :

namespace Email.Services
{
   public interface IEmailSender // don't forget the public modifier
   {
       void Send(string toAddress, string subject, string body, bool sendAsync = true);
   }
}

 

 

Open the EmailSender.cs file and implement the IEmailSender interface

using Microsoft.Extensions.Configuration;
using MimeKit;
 
namespace Email.Services
{
   public class EmailSender : IEmailSender
   {
       private string _smtpServer;
       private int _smtpPort;
       private string _fromAddress;
       private string _fromAddressTitle;
       private string _username;
       private string _password;
       private bool _enableSsl;
       private bool _useDefaultCredentials;
 
       public EmailSender(IConfiguration configuration) // configuration is automatically added to DI in ASP.NET Core 3.0
       {
           _smtpServer = configuration["Email:SmtpServer"];
           _smtpPort = int.Parse(configuration["Email:SmtpPort"]);
           _smtpPort = _smtpPort == 0 ? 25 : _smtpPort;
           _fromAddress = configuration["Email:FromAddress"];
           _fromAddressTitle = configuration["FromAddressTitle"];
           _username = configuration["Email:SmtpUsername"];
           _password = configuration["Email:SmtpPassword"];
           _enableSsl = bool.Parse(configuration["Email:EnableSsl"]);
           _useDefaultCredentials = bool.Parse(configuration["Email:UseDefaultCredentials"]);
       }
 
       public async void Send(string toAddress, string subject, string body, bool sendAsync = true)
       {
           var mimeMessage = new MimeMessage(); // MIME : Multipurpose Internet Mail Extension
           mimeMessage.From.Add(new MailboxAddress(_fromAddressTitle, _fromAddress));
           mimeMessage.To.Add(new MailboxAddress(toAddress));
           mimeMessage.Subject = subject;
 
           var bodyBuilder = new MimeKit.BodyBuilder
           {
               HtmlBody = body
           };
           mimeMessage.Body = bodyBuilder.ToMessageBody();
 
           using (var client = new MailKit.Net.Smtp.SmtpClient())
           {
               client.Connect(_smtpServer, _smtpPort, _enableSsl);
               client.Authenticate(_username, _password); // If using GMail this requires turning on LessSecureApps : https://myaccount.google.com/lesssecureapps
               if (sendAsync)
               {
                   await client.SendAsync(mimeMessage);
               }
               else
               {
                   client.Send(mimeMessage);
               }
               client.Disconnect(true);
           }
       }
   }
}

The EmailSender class is initialized with all the configuration variables from appsettings (running on the development machine configuration is loaded from appsettings.development.json while then running on the production machine configuration will be loaded from appsettings.json) 

 

 

Create the user interface for sending an email, open Index.cshtml and fill in the following code :

<style>
   #divEmailForm {
       display:grid;
       grid-gap: 5px;
       grid-template-columns: 100px 200px;
   }
</style>
 
<div style="margin:0 auto;">
   <form action="/Home/SendEmail" method="post">
       <div id="divEmailForm">
           <div><label>Email</label></div>
           <div><input name="toAddress" placeholder="Email" style="width:100%;" /></div>
           <div><label>Subject</label></div>
           <div><input name="subject" placeholder="Subject" style="width:100%;" /></div>
           <div><label>Message</label></div>
           <div><textarea name="body" placeholder="Message" style="width:100%;height:150px;overflow:hidden;"></textarea></div>
           <div></div>
           <div><button type="submit">Send</button></div>
       </div>
   </form>
</div>

In the user interface code above there is a submit button called Send, which will post the form to the http endpoint specified in the form's action attribute "/Home/SendMail".

 

 

 Open HomeController.cs and add the "/Home/SendMail" endpoint by creating an Action called SendMail. In the SendMail action we will activate the EmailSender.Send(...) function and then navigate the user back to the original user interface. 

using System.Linq;
using Microsoft.AspNetCore.Mvc;
 
using Email.Services;
 
namespace Email.Controllers
{
   public class HomeController : Controller
   {
       private IEmailSender _emailSender;
 
       public HomeController(IEmailSender emailSender)
       {
           _emailSender = emailSender;
       }
 
       public IActionResult Index()
       {
           return View();
       }
 
       [HttpPost]
       public IActionResult SendEmail()
       {
           var toAddress = HttpContext.Request.Form["toAddress"].FirstOrDefault();
           var subject = HttpContext.Request.Form["subject"].FirstOrDefault();
           var body = HttpContext.Request.Form["body"].FirstOrDefault();
 
           _emailSender.Send(toAddress, subject, body);
 
           return RedirectToAction("Index");
       }
   }
}

 

 

Sending an email

At last we are ready to test if we can actually send an email.

 

  1. Press ctrl+F5 in the Visual Studio to compile, start IISExpress and open a browser tab on the Email project url - you should see a user interface for sending emails.
  2. Fill in some values for the 3 fields and press the Send button
    • Email : rasserrummel@outlook.com (one of my dummy emails, you should use one of your own emails preferably not your Gmail email)
    • Subject : subject test 1
    • Message : body test 1
  3. Success - the email was send to Gmail Smtp and forwarded to rasserrummel@outlook.com.

 

Congratulation ! - you are now able to send emails from ASP.NET Core to any email address via Gmail Smtp.

 

 

Now that we have a working email sending application, it is time to setup email sending infrastructure on a production server.

 

 

 

Installing an email server on your production server

To send emails from asp.net core on your production, typically you may be using an email server provided by your hosting company or you may be using a dedicated 3.party SMTP service (likely costly), however for one reason or another it is also often the case that it is a better option to setup your own SMTP server - here I will show how to do that.

 

While we used Google SMTP on our development machine, we will use hMailServer on our production machine.

 

However, while we got the DNS part part of the email sending infrastructure automatically taken care of then using Google SMTP, we need to setup DNS then using our own email server.

 

 

Configure DNS for your Email Server

You need to add an MX record to your DNS for mail clients and other mail servers to find your mail server.

 

Including support records, you need 3 DNS records - here exemplified for the topiqs.online domain : 

TypeHostValueDescription
A@5.231.220.25Main A-record as they will look on most DNS Servers hosted by domain name registrars.
Amail5.231.220.25Specify a sub-domain called mail and specify the IP on which the sub-domain (mail.topiqs.online) is hosted, here hosted on the same server as the topiqs.online website (the poorer you are the more likely you have the email server on the same host as your web server).
MX@mail.topiqs.onlineThe actual MX record that email clients & other email servers are looking up then resolving your-name@topiqs.online. The MX record is the email clients and other email servers to find your email server on the IP address specified for mail.topiqs.online (above).

 

(You of course need to change topiqs.online to your own domain and change 5.231.220.25 to the IP address of your own server).

 

Use nslookup to test your MX record :

  1. Open a command prompt
  2. shell> nslookup -type=mx topiqs.online :
    • First section have 2 lines specifying the DNS server that was used :
      • Server: UnKnown : my router does not have a domain name
      • Address: 192.168.1.3 which is my router
    • Non-authoritative answer : yes my router is NOT the authoritative DNS for topiqs.online, it
    • MX record points to mail.topiqs.online (as specified in the above table)
    • mail.topiqs.online have IP 5.231.220.25 - this IP is read by mail servers wanting to send mail messages to anything@topiqs.online.
  3. shell> nslookup -type=soa topiqs.online : get the authoritative dns server for topiqs.online
  4. shell> nslookup -type=mx topiqs.online dns1.registrar-servers.com : use the authoritative dns server to lookup MX record for topiqs.online (note that the actual dns server used to looking up the MX record is not necessarily the primary authoritative dns server but can be any secondary authoritative dns server, eg. in the screenshot it is dns5. Try to issue the command many times and you will see different dns mirrors sometimes the actual primary dns server)

 

PTR record

Note that some email servers (most notably gmail) will NOT accept email sent from your email server, if there is no PTR record for your email servers hostname (above that would be mail.topiqs.online). The PTR record allows to resolve an IP address to a hostname (called reverse lookup), in the above example that would be : resolving 5.231.220.25 to mail.topiqs.online.

 

  • A-record : resolving hostname to IP - above it would be mail.topiqs.online to 5.231.220.25
  • PTR-record : resolving IP to hostname - above it would be 5.231.220.25 to mail.topiqs.online

Say that a mail messages was sent to the gmail server from my email server on 5.231.220.25 and the mail message contains a hostname field with the value "mail.topiqs.online" - the gmail server will request a PTR record for 5.231.220.25 and compare with the mail message hostname field to see if they match validating whether the mail message is indeed sent from the hostname that it is saying it is.

 

To setup a PTR record you will need to ask your hosting provider to set it up for you.

 

Use nslookup to test your PTR record :

  1. Open a command prompt.
  2. shell> nslookup -type=ptr 5.231.220.25 : reverse lookup is working for the topiqs email server on 5.231.220.25.

 

Ok, with the DNS setup and DNS testing out of the way, we can continue to install hMailServer.

 

 

Install hMailServer

On your production server :

  1. Navigate to hMailServer official download page : https://www.hmailserver.com/download
  2. Download the newest version of hMailServer
  3. Install hMailServer (official installation guide)
    1. Double click the downloaded installer file
    2. Click Next on the install welcome screen
    3. On the License Agreement screen be sure to select "I accept the agreement" and then click Next
    4. Select install location - don't change the default location (unless you have a good reason) and then click Next
    5. Yes, we want to install both the mail server AND the Administrative tools
    6. Keep the default folder name, hMailServer
    7. You are ready to install - click the install button
    8. Wait while the 2 programs (mail server AND Administrative tools) installs
    9. Set a password for the Administrator tools
    10. FINISHED - tick the "Run hMailServer Administrator" (to open Administrative tools) and click the Finish button.
    11. Administrative tools ready to connect

 

Configure hMailServer

On your production server

  1. Start the hMailServer Administrator App.
  2. hMailServer Administrator App ask you to connect to Administrator tools on localhost.
  3. Input the password that your supplied in the installation process above.
  4. The hMailServer Administrator tools - ready to configure (official configuration guide).
    1. Configure Domains :
      1. Select Domains in the left pane and then click the Add button in the right pane
      2. Input your domain name, for me it is topiqs.online
    2. Configure Accounts :
      1. Expand the domain for which you want to add accounts and select Accounts
      2. Under the expanded domain select Accounts
    3. Configure Hostname : typically an email servers hostname is different from the email domain(s) that it hosts - in our case the hMailServer hostname is mail.topiqs.online (as specified in the DNS above), while the email domains hosted is topiqs.online (only 1 email domain). Some email servers will reject mail messages sent from a mail server that does not publish it's hostname.
      1. Set the hMailServers hostname to the same domain you did in the DNS server, in this tutorial it was mail.topiqs.online :
        1. Expand Settings (left pane)
        2. Expand Protocols (left pane)
        3. Select SMTP (left pane)
        4. Select Delivery of e-mail (right pane)
        5. Input your hostname in the "Local host name" text field and Click Save
    4. Configure IP range : IP ranges are used by hMailServer to specify from which IP addresses hMailServer accepts what kinds of connections (official IP range documentation)
      1. Navigate to IP ranges :
        1. Expand Settings (left pane)
        2. Expand Advanced (left pane)
        3. Expand & Select IP ranges (left pane)
      2. hMailServer come pre-configured with 2 IP ranges called "My computer" & "Internet"
      3. Delete the "Internet" rule : this email server is only for sending emails created by our C# application - we don't want to receive nor relay any emails.
      4. Edit the "My computer" rule :
        1. Select the "My computer" rule and press edit
        2. Be sure that the IP range is setup to the production server IP address (if you have your email server on a different IP than your C# application, you need to include the IP of your C# application either by extending the IP range or adding a new IP range)

          Note that I have left the POP3 & IMAP protocols checked even though in my setup they will not be used, however they will do no harm since only connections from within the server will be allowed and if you want to test your email server it is convenient to allow these 2 protocols.

 

Using telnet to test the email server

Testing port 25

Port 25 is default used by clients and other email servers to send mail messages to you email server and also your email server will use port 25 to send mail messages to other email servers - in a default setup you need port 25 to be open.

 

Depending on your hosting situation, port 25 may default be closed, eg. if you have a VPS at a hosting company, the hosting company will typically not allow any traffic on port 25 - in this situation you will need your hosting company to open port 25 for relevant IP addresses on your VPS (my hosting company warned me that it is a bad idea, but allowed me use of port 25 after I accepted that they could close me down immediately in case of spam mails sent from my server).

 

There are too many different setup possibilities to go through them all here, however we can test port 25 to be sure that it is correctly setup :

  1. Test that your email server correctly connects on port 25
    1. Open a command prompt on your production server (the same host there your email server is running)
    2. shell> telnet 5.231.220.25 25 : specifying IP and Port
    3. Connected ! - port 25 is open and hMailServer is answering
  2. Test whether remote clients and other email servers can connect to your email server on port 25
    1. Open a command prompt on NOT your production server (eg. open a command prompt on your development machine)
    2. shell> telnet 5.231.220.25 25 : specifying IP (production server) and Port
    3. Failure ! - the email server on mail.topiqs.online does NOT allow any remotely initiated connection - in my case it is because the mail.topiqs.online email server is only used for sending emails from the topiqs.online application, it is not supposed to receive any emails from clients nor other email servers.

 

Send email to hMailServer using SMTP :

  1. shell> telnet mail.topiqs.online 25 :
    • a connection is established (with a server on port 25)
      • 220 : server is ready for SMTP dialog (ok it is an smtp server)
      • ESMTP : Extended SMTP - supports additional functionality especially TLS
  2. smtp session> ehlo mail.topiqs.online : ehlo is to identify the client ip or domain (here same domain as the server) and since we use ehlo instead of helo we hint that we may be using extended smtp commands
  3. smtp session> auth login :
    • 334 VXNlcm5hbWU6 : asking you to input a base64 encoding or the email account you want to authenticate with.
  4. smtp session>VG9waXFzQG1haWwudG9waXFzLm9ubGluZQ== : base64 encoding of the email account I want to authenticate with, here topiqs@topiqs.online (online base64 encoder)
    • 334 UGFzc3dvcmQ6 : asking you to input a base64 encoding of the password for the just supplied email account
  5. smtp session> xxxxYWx0xxxx : base64 encoding of password for the just supplied email account
    • 236 authenticated : authentication was a success - you can now send mail.
  6. smtp session> mail from: somebody@somedomain.com : start by specifying who the mail is from - no need to use an existing account, here I use a made up account.
  7. smtp session> rcpt to: rasserrummel@outlook.com :
  8. smtp session> data : tell the server that what is coming next is the email data content
    • 354 OK, send. : server starts mail input
  9. smtp session> subject: telnet subject 1 : create the subject field and initialize it
  10. smtp session> 
                              telnet body 1
                              another line in the body
                              : you can have many lines of body content
  11. smtp session> . : the dot command is used to end of email and should be 2 lines down.
    • 250 Queued <xx seconds> : email queued for relaying.
  12. SUCCESS - the email was sent and recieved by outlook.com.

 

 

Retrieving email from hMailServer using IMAP

This test is NOT necessary for our purpose as in this tutorial we only intend to use hMailServer for sending emails not receiving emails, however we do this test just for the fun of it

 

IMAP commands must be pre-fixed with a 'tag' that identifies the session - this allows multiple sessions to run at the same time (which again allows commands to be asyncronous). A tag can be anything we make up ourself and in this example it will just be 'a' (though for a real IMAP client you will typically use more descriptive tags).

 

Before this example gives meaning, you need to send an email to an account on the hMailServer, you can use the above example (telnet smtp) to send a test email.

 

  1. shell> telnet mail.topiqs.online 143 :
    • connection is established (with a server on port 143)
      • OK IMAPrev1 : connected to an IMAP server specifying it's capabilities, here IMAP revision 1.
  2. imap session> a login rasmus@topiqs.online <password> :
    • a : the tag specifying the session - in the rest of this session we must prefix all commands with 'a'.
    • login : the way we choose to login (there are 2 other ways to login, which we will not explore here) - login must be postfixed with an email address existing on the server and then the password for that email address.
    • a OK LOGIN completed : successfully logged in.
  3. imap session> a list "*" "*" : list all mailboxes (second "*" specifies that we want any mailbox) (official list command)
    • current user (rasmus@topiqs.online) have 3 mailboxes, INBOX, Sent & Trash
      • \HasNoChildren : no sub mailbox
      • "." : hierarchical delimeter (not in use in this case)
      • "INBOX" : name of mailbox
  4. imap session> a select "inbox" :
  5. imap session> s search unseen : display all the unseen messages (just for fun)
  6. fetch : used to fetch messages from the selected mailbox, here I show a few examples of how the fetch command can be used :
    • imap session> f fetch 1:6 (body[header.fields fetch(subject)]) : fetch message 1 to 6 from the selected mailbox (inbox) and display only the subject
    • imap session> a fetch 6 full : SUCCESS - we retrieved an email.
    • imap session> a fetch 6 rfc822.header : more human readable than "full"
  7. imap session> a logout : end this session

 

Ok, your email server seems to work, let's try to send an email from the ASP.NET Core application.

 

Sending an email from your production server

This is our final goal - that we can send emails from ASP.NET Core on our production server using our own hMailServer installation.

 

  1. In Visual Studio open appsettings.json and insert the following code (here I have used the values used for topiqs.online, however you should insert values reflecting your own hMailServer settings)
    {
        "Email": {
            "SmtpServer": "mail.topiqs.online",
            "SmtpPort": "25",
            "SmtpUsername": "topiqs@topiqs.online",
            "SmtpPassword": "yourPassword",
            "FromAddress": "topiqs@mail.topiqs.online",
            "FromAddressTitle": "Topiqs",
            "EnableSsl": "false",
            "UseDefaultCredentials": "false"
        }
    }
  2. Upload your ASP.NET Core application from your development machine to your production server using whatever publishing mechanism you usually use.
  3. Start your application and navigate to the email sending UI, here https://topiqs.online/home/testemail (I added the UI to topiqs.online but could not use /Home/Index since that path was already in use, so I changed the path to /Home/TestEmail).
  4. Send an email to one of your email addresses.
  5. SUCCESS - test that your email arrived.

 

Congratulations - you now have a production ready ASP.NET Core application able to send emails.

 

 

Appendix : Email Related Acronyms

 

  • SMTP : Simple Mail Transfer Protocol : Port 25 : used by mail clients to send mail messages to mail servers as well as by mail servers to send mail messages to other mail servers.
  • SMTP SSL :  : Port 465
  • SMTP TSL : : Port 587
  • POP3 : Post Office Protocol : Port 110 : used by a local email client to retrieve mail messages from a remote server, however then downloading a mail message using the POP3 protocol that mail message will be deleted on the server (so you cannot access that mail message from another email client)
  • POP3 Secure : Port 995 :
  • IMAP : Internet Message Access Protocol : Port 143 : used by a local email client to retrieve mail messages from a remote server. IMAP supports multiple email clients (while POP3 only support 1 email client) because IMAP allows mail message to stay on the server then downloaded.
  • IMAP SSL : Port 993 :
  • MTA : Mail Transfer Agent (smtp server) : An MTA receives and sends out mail default on port 25 (465 for SSL & 587 for TSL).
  • MDA : Mail Delivery Agent : An MDA makes messages received by MTA available for download using eg. IMAP or POP3.
  • MUA : Mail User Agent : A MUA is the email program you use to create email messages and to download and read them.
  • LDA : Local Delivery Agent : Then an MTA decides that it is itself the final MTA destination for an email message, the MTA instead of forwarding the email message to yet another MTA needs to store the email message on local storage.
  • MIME : Multipurpose Internet Mail Extension.
  • MX : Mail Exchanger : DNS record used by web servers to find the IP addresses of email domains, eg. if your hMailServer need to send an email to abc@gmail.com, your hMailServer will need the IP of gmail.com mail server - hMailServer will request an MX record for gmail.com from any DNS server too get the IP address (the reason your mail server cannot use an A-record is because the mail server of gmail.com may be hosted on a different IP than the gmail.com website - so the A-record and the MX-record may be on different IP's)
  • PTR : Pointer : DNS record with an IP as the entry key and a hostname as the value (resolving IP to host) and since this is opposite to the A-record (resolving host to IP), PTR records are also called reverse lookup records. PTR records are used mostly by web servers to confirm that a mail message is indeed sent from the hostname that the message claims to be sent from.

 

Understanding Emailing Flow

In the below picture email is sent from an account rasmus@test1.com to another account asger@test2.com

 

 

 

Appendix : Sending emails with attachments

Building on the main email project, we need to :

  1. Add UI for uploading files for email attachments (Index.cshtml).
  2. Build an infrastructure for transporting these files to the email sending code (IEmailSender.cs & HomeController.cs).
  3. Amend the email sending code to attach these files to the email sent (EmailSender.cs).

 

Ok, I better show the full code for the files we need to change :

  1. Open Index.cshtml to add a file upload button to the UI (3 changes)
    <style>
       #divEmailForm {
           display:grid;
           grid-gap: 5px;
           grid-template-columns: 100px 200px;
       }
    </style>
     
    <div style="margin:0 auto;">
       <form action="/Home/SendEmail" method="post" enctype="multipart/form-data"> <!-- Here (1) -->
           <div id="divEmailForm">
               <div><label>Email</label></div>
               <div><input name="toAddress" placeholder="Email" style="width:100%;" value="rasserrummel@outlook.com" /></div>
               <div><label>Subject</label></div>
               <div><input name="subject" placeholder="Subject" style="width:100%;" value="subject " /></div>
               <div><label>Message</label></div>
               <div><textarea name="body" placeholder="Message" style="width:100%;height:150px;overflow:hidden;">body </textarea></div>
               <div><label>Attachments</label></div> <!-- and here (2) -->
               <div><input name="attachments" type="file" multiple /></div> <!-- and here (3) -->
               <div></div>
               <div><button type="submit">Send</button></div>
           </div>
       </form>
    </div>
  2. Open IEmailSender.cs to add an attachment argument to the Send interface (2 changes)
    using Microsoft.AspNetCore.Http; // Here (1)
     
    namespace Email.Services
    {
       public interface IEmailSender
       {
           void Send(string toAddress, string subject, string body, bool sendAsync = true, IFormFileCollection attachments = null); // and here (2)
       }
    }
  3. Open HomeController.cs to retrieve the uploaded files from the UI and to pass the uploaded files along to the real Send function (3 changes)
    using System.Linq;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.AspNetCore.Http; // Here (1)
     
    using Email.Services;
     
    namespace Email.Controllers
    {
       public class HomeController : Controller
       {
           private IEmailSender _emailSender;
     
           public HomeController(IEmailSender emailSender)
           {
               _emailSender = emailSender;
           }
     
           public IActionResult Index()
           {
               return View();
           }
     
           [HttpPost]
           public IActionResult SendEmail()
           {
               var toAddress = HttpContext.Request.Form["toAddress"].FirstOrDefault();
               var subject = HttpContext.Request.Form["subject"].FirstOrDefault();
               var body = HttpContext.Request.Form["body"].FirstOrDefault();
               var uploadedFiles = HttpContext.Request.Form.Files; // and here (2)
     
               _emailSender.Send(toAddress, subject, body, attachments: uploadedFiles); // and here (3)
     
               return RedirectToAction("Index");
           }
       }
    }
  4. Change EmailSender.cs to implement adding the uploaded files as attachment to the email message (4 changes)
    using Microsoft.Extensions.Configuration;
    using Microsoft.AspNetCore.Http; // Here (1)
    using System.IO; // and here (2)
     
    using MimeKit;
     
    namespace Email.Services
    {
       public class EmailSender : IEmailSender
       {
           private string _smtpServer;
           private int _smtpPort;
           private string _fromAddress;
           private string _fromAddressTitle;
           private string _username;
           private string _password;
           private bool _enableSsl;
           private bool _useDefaultCredentials;
     
           public EmailSender(IConfiguration configuration)
           {
               _smtpServer = configuration["Email:SmtpServer"];
               _smtpPort = int.Parse(configuration["Email:SmtpPort"]);
               _smtpPort = _smtpPort == 0 ? 25 : _smtpPort;
               _fromAddress = configuration["Email:FromAddress"];
               _fromAddressTitle = configuration["FromAddressTitle"];
               _username = configuration["Email:SmtpUsername"];
               _password = configuration["Email:SmtpPassword"];
               _enableSsl = bool.Parse(configuration["Email:EnableSsl"]);
               _useDefaultCredentials = bool.Parse(configuration["Email:UseDefaultCredentials"]);
           }
     
           public async void Send(string toAddress, string subject, string body, bool sendAsync = true, IFormFileCollection attachments = null) // and here (3)
           {
               var mimeMessage = new MimeMessage();
               mimeMessage.From.Add(new MailboxAddress(_fromAddressTitle, _fromAddress));
               mimeMessage.To.Add(new MailboxAddress(toAddress));
               mimeMessage.Subject = subject;
     
               var bodyBuilder = new MimeKit.BodyBuilder
               {
                   HtmlBody = body
               };
     
               /* and here (4) start */
               if (attachments != null)
               {
                   foreach (IFormFile attachment in attachments)
                   {
                       if (attachment.Length > 0)
                       {
                           using (var memoryStream = new MemoryStream())
                           {
                               await attachment.CopyToAsync(memoryStream);
                               bodyBuilder.Attachments.Add(attachment.FileName, memoryStream.ToArray(), ContentType.Parse(attachment.ContentType));
                           }
                       }
                   }
               }
               /* and here (4) end */
     
               mimeMessage.Body = bodyBuilder.ToMessageBody();
     
               using (var client = new MailKit.Net.Smtp.SmtpClient())
               {
                   client.Connect(_smtpServer, _smtpPort, _enableSsl);
                   client.Authenticate(_username, _password);
                   if (sendAsync)
                   {
                       await client.SendAsync(mimeMessage);
                   }
                   else
                   {
                       client.Send(mimeMessage);
                   }
                   client.Disconnect(true);
               }
           }
       }
    }
  5. In Visual Studio press ctrl+F5 to open the email sending UI in a browser.
  6. Fill in the email sending UI
    1. an email address that belongs to yo
    2. a test subject
    3. a test body
    4. press the "Choose Files" button to select a couple of files
    5. press the send button
  7. Success - test that your email have arrived and that it have the expected attachments.

 

 

Appendix : Sending emails with inline images

While MailKit does support inline images, the support is weak and the most important method to create inline images seems to not work.

 

To embed an image inline in an email message using MailKit, you need to :

  1. Add the image to BodyBuilder.LinkedResources using a path to the image (it does NOT work then adding the image as a byte array, you MUST use a path) . "Linked resources are a special type of attachment which are linked to from the HtmlBody" (official).
  2. Create a ContentId for the linked image.
  3. Add an html image tag to the html that sets the BodyBuilder.HtmlBody and in the image tag set the src-attribute to the ContentId assigned the linked image.

 

Ok, let's see the code :

  1. Open EmailSender.cs to hardcode embedding an image into any email we send (2 changes)
    using Microsoft.Extensions.Configuration;
    using Microsoft.AspNetCore.Http;
    using System.IO;
     
    using MimeKit;
    using MimeKit.Utils; // Here (1)
     
    namespace Email.Services
    {
       public class EmailSender : IEmailSender
       {
           private string _smtpServer;
           private int _smtpPort;
           private string _fromAddress;
           private string _fromAddressTitle;
           private string _username;
           private string _password;
           private bool _enableSsl;
           private bool _useDefaultCredentials;
     
           public EmailSender(IConfiguration configuration)
           {
               _smtpServer = configuration["Email:SmtpServer"];
               _smtpPort = int.Parse(configuration["Email:SmtpPort"]);
               _smtpPort = _smtpPort == 0 ? 25 : _smtpPort;
               _fromAddress = configuration["Email:FromAddress"];
               _fromAddressTitle = configuration["FromAddressTitle"];
               _username = configuration["Email:SmtpUsername"];
               _password = configuration["Email:SmtpPassword"];
               _enableSsl = bool.Parse(configuration["Email:EnableSsl"]);
               _useDefaultCredentials = bool.Parse(configuration["Email:UseDefaultCredentials"]);
           }
     
           public async void Send(string toAddress, string subject, string body, bool sendAsync = true, IFormFileCollection attachments = null)
           {
               var mimeMessage = new MimeMessage();
               mimeMessage.From.Add(new MailboxAddress(_fromAddressTitle, _fromAddress));
               mimeMessage.To.Add(new MailboxAddress(toAddress));
               mimeMessage.Subject = subject;
     
               var bodyBuilder = new MimeKit.BodyBuilder
               {
                   HtmlBody = body
               };
     
               /* and here (2) start */ 
               var embeddedImage = bodyBuilder.LinkedResources.Add(@"D:\_TEMP\email.png"); // change the path to an image on your own disk
               embeddedImage.ContentId = MimeUtils.GenerateMessageId();
               bodyBuilder.HtmlBody = bodyBuilder.HtmlBody + @"<img src=""cid:" + embeddedImage.ContentId + @""" />";
               /* and here (2) end */
     
               if (attachments != null)
               {
                   foreach (IFormFile attachment in attachments)
                   {
                       if (attachment.Length > 0)
                       {
                           using (var memoryStream = new MemoryStream())
                           {
                               await attachment.CopyToAsync(memoryStream);
                               bodyBuilder.Attachments.Add(attachment.FileName, memoryStream.ToArray(), ContentType.Parse(attachment.ContentType));
                           }
                       }
                   }
               }
     
     
               mimeMessage.Body = bodyBuilder.ToMessageBody();
     
               using (var client = new MailKit.Net.Smtp.SmtpClient())
               {
                   client.Connect(_smtpServer, _smtpPort, _enableSsl);
                   client.Authenticate(_username, _password); // If using GMail this requires turning on LessSecureApps : https://myaccount.google.com/lesssecureapps
                   if (sendAsync)
                   {
                       await client.SendAsync(mimeMessage);
                   }
                   else
                   {
                       client.Send(mimeMessage);
                   }
                   client.Disconnect(true);
               }
           }
       }
    }
    "Linked resources are a special type of attachment which are linked to from the HtmlBody" (official)
     
  2. In Visual Studio press ctrl+F5 to open the email sending UI in a browser.
  3. Fill in the email sending UI (in our code the embedded image is hardcoded, so there is no image to select) and press the Send button.
  4. Success - the image is embedded indeed.

 

Note that even if the BodyBuilder.LinkedResources.Add() function have overloads for linking images by byte arrays, it does not not work. Instead in a scenario there the images to be embedded are user defined, MailKit only offers an inconvenient solution : copying all the images to disk on the server and then linking the images by path.

 

 

Appendix : Common Errors & Solutions

Error : MailKit.Security.SslHandshakeException "An error occurred while attempting to establish an SSL or TLS connection".

 

Reason : this will of course happen if the port you try to connect to does not support the cryptographic protocol you are using. It happened for me then trying to connect to Gmail SMTP using port 587 then I should have used 465.

 

 

Error : MailKit.Security.AuthenticationException "AuthenticationInvalidCredentials: 5.7.8 Username and Password not accepted".

 

Reason 1 : this can be a case of bad credentials then connecting to Gmail SMTP - either your username or password is wrong.

Reason 2 : this can also be a case of OAuth version mismatch, eg. GMail SMTP using OAuth 2.0 while your client (in our case MailKit) does not - be sure to enable LessSecureApps for the Google account you use for authentication.

 

 

 

 Add to favourites  Upvote report
No comments yet
x
x
Bookmark
Share Anything
Collaborate
Blog