How to test email and SMS in .NET

Learn how to automate test email and SMS messages in .NET, using Mailosaur.

1. Create a Mailosaur account

If you already have an account, skip to step 2.

To create a new trial account, sign up here.

2. Create a sample project

Install .NET

To see if you already have .NET installed, open a terminal window and run this command:

dotnet --version

If .NET is installed, you’ll see a version number. If you see an error instead, then download .NET from Microsoft and install it.

Create a new project

Run each of these commands to create a new .NET project:

mkdir EmailTests
cd EmailTests
dotnet new console

Install the Mailosaur .NET library

Run this command to install the Mailosaur NuGet package:

dotnet add package mailosaur

3. Send email to your Mailosaur server

Servers allow you to group tests, permissions, and other settings together. Each server has a Server ID, a domain name. You need these values to both send email to Mailosaur, and to set up automated testing.

You also need an API key to use. You can learn more about creating API keys here.

Retrieve your server’s attributes

  1. Go to the Servers page in the Mailosaur Dashboard.
  2. Click on the name of the server you want to test with.
  3. Click on the API tab.
  4. Make a note of the Server ID, domain name and API key.

Send an email to your server

If the domain name of your server above was:

example.mailosaur.net

Then you can send an email to it with these steps:

  1. Open up an email client and send an email to anything@example.mailosaur.net
  2. Go to the Servers page in the Mailosaur Dashboard.
  3. Click on the name of the server you sent an email to.
  4. Confirm the email is there. Note that some services (like Gmail) may take 10-20 seconds to send a message through.

To learn more, read our guide on sending email to Mailosaur.

4. Find an email for automated testing

Now that you have a sample project, your server’s credentials, and an email to test, then you’re ready to continue.

Open the file in your new project called Program.cs and type or paste in this code sample, replacing the template code with the values from step 3 above:

using System;
using Mailosaur;
using Mailosaur.Models;

namespace EmailTests
{
  class Program
  {
    static void Main(string[] args)
    {
      // Available in the API tab of a server
      var apiKey = "YOUR_API_KEY";
      var serverId = "SERVER_ID";
      var serverDomain = "SERVER_DOMAIN";

      var mailosaur = new MailosaurClient(apiKey);

      // Wait for an email to arrive, matching this search criteria
      var criteria = new SearchCriteria() {
          SentTo = "anything@" + serverDomain
      };
      var email = mailosaur.Messages.Get(serverId, criteria);

      // If we have an email, print the subject
      Console.WriteLine("Subject: " + email.Subject);
    }
  }
}

This code connects to Mailosaur and looks for any email that has been sent to the address provided in the search criteria.

Save your changes and run the code:

dotnet run

If everything is set up correctly, you should see the subject line of the last email you sent, printed to screen:

Subject: My example email

Troubleshooting

If you see an error, e.g. ‘No matching messages found in time’:

  • Make sure you have set the sent to address correctly in your code.
  • Ensure that you have sent an email to the sent to address (check this is visible in the Mailosaur Dashboard).
  • Note that by default, the get method will only look for messages that were received by Mailosaur within the last hour. You can override this using the receivedAfter option (see library reference below).

5. Start writing tests

Now that you have a working project that fetches an email, you can use this to begin writing tests for various pieces of functionality.

Check out these guides on the most common test cases:

Library reference

The .NET client library gives you access to several other methods.

Messages

Messages is the collective name given to the email and/or SMS messages that are sent into Mailosaur for testing. The message object contains everything you need to perform in-depth automated testing.

Messages.Get(server, criteria, options)

Waits for a message to be found. Returns as soon as a message matching the specified search criteria is found.

This is the most efficient method of looking up a message, therefore we recommend using it whenever possible.

var message = mailosaur.Messages.Get("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
});

To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.

Criteria
  • SentFrom The full email address from which the target message was sent.
  • SentTo The full email address to which the target message was sent.
  • Subject The subject line of the target email.
  • Body Search for part of the message body.
  • Match If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.
Timeout
  • timeout Specify how long to wait for a matching result (in milliseconds, default value is 10 seconds).
  • receivedAfter Limits results to only messages received after this date/time (default 1 hour ago).
// Search all messages received after midnight 5th Jan 2020
var message = mailosaur.Messages.Get("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
}, receivedAfter: new DateTime(2020, 1, 5));

Messages.List(server, options)

Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.

Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call GetById. Alternatively, we recommend using the Get method, which is a far more efficient approach.
// List the most recent messages
var result = mailosaur.Messages.List("SERVER_ID");

// Get the most recent message (the first one in the list)
var message = result.Items[0];

Console.WriteLine("Subject: " + message.Subject);
Options
  • receivedAfter Allows you to customise how far back to look for messages.
  • page Used alongside itemsPerPage to paginate through results. This is zero-based, meaning 0 is the first page of results.
  • itemsPerPage A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.
// List all results received after midnight on 3rd January 2020
// Limit results to the first 10 matches only.
var result = mailosaur.Messages.List("SERVER_ID", 0, 10, new DateTime(2020, 1, 3));

Messages.Search(server, criteria, options)

Returns a list of messages matching the specified search criteria, in summary form. The messages are returned sorted by received date, with the most recently-received messages appearing first.

Message summaries The method returns a message summary, rather than the full message object. This means that several properties, like the message body, are not included. To get this data, you’ll need to call GetById. Alternatively, we recommend using the Get method, which is a far more efficient approach.
var result = mailosaur.Messages.Search("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
});

// Get the most recent match
var message = result.Items[0];

Console.WriteLine("Subject: " + message.Subject);
Criteria
  • sentFrom The full email address from which the target message was sent.
  • sentTo The full email address to which the target message was sent.
  • subject The subject line of the target email.
  • body Search for part of the message body.
  • match If set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.
Options
  • timeout If provided, determines how long to wait for a matching result (provided in milliseconds).
  • errorOnTimeout When set to false, an error will not be throw if timeout is reached (default: true).
  • receivedAfter Allows you to customise how far back to look for messages.
  • page Used alongside itemsPerPage to paginate through results. This is zero-based, meaning 0 is the first page of results.
  • itemsPerPage A limit on the number of results to be returned. This can be set between 1 to 1000, with the default being 50.
// Search for all messages sent to someone@SERVER_ID.mailosaur.net,
// received after midnight on 3rd Jan 2020. Limit results to
// the first 10 matches only.
var result = mailosaur.Messages.Search("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
}, page: 0, itemsPerPage: 10, receivedAfter: new DateTime(2020, 1, 3));

Messages.GetById(id)

Retrieves the detail for a single email message. Must be used in conjunction with either List or Search in order to get the unique identifier for the required message. We always recommend using the Get method instead.

var result = mailosaur.Messages.List("SERVER_ID");
var messageId = result.Items[0].Id;

var message = mailosaur.Messages.GetById(messageId);

Console.WriteLine("Subject: " + message.Subject);

Messages.Delete(id)

Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.

mailosaur.Messages.Delete(messageId);

Messages.DeleteAll(server)

Permanently deletes all messages held by the specified server. Also deletes any attachments related to each message. This operation cannot be undone.

mailosaur.Messages.DeleteAll("SERVER_ID");

Servers

Servers contain all the configuration and set up for.

Servers.List()

Returns a list of your virtual servers. Servers are returned sorted in alphabetical order.

ServerListResult result = mailosaur.Servers.List();

Console.WriteLine("You have a server called: " + result.Items[0].Name);

Servers.Create(server)

Creates a new virtual server. Only the name property is required to create a new server via the API.

var options = new ServerCreateOptions("My email tests");
mailosaur.Servers.Create(options);

Servers.Get(id)

Retrieves the detail for a single server. Simply supply the unique identifier for the required server.

var server = mailosaur.Servers.Get("SERVER_ID");

Servers.Update(id, server)

Updates a single server.

var retrievedServer = mailosaur.Servers.Get("SERVER_ID");
retrievedServer.Name = "Updated server name";

mailosaur.Servers.Update(retrievedServer.Id, retrievedServer);

Servers.Delete(id)

Permanently deletes a server. Also deletes all messages and associated attachments within the server. This operation cannot be undone.

mailosaur.Servers.Delete("SERVER_ID");

Servers.GenerateEmailAddress(id)

Utility method to help you generate a random email address for a given server.

var emailAddress = mailosaur.Servers.GenerateEmailAddress("SERVER_ID");

Console.WriteLine(emailAddress); // "bgwqj@SERVER_ID.mailosaur.net"

To learn about Server IDs, and what to replace SERVER_ID with, see sending email to Mailosaur.

Files

Files.GetEmail(messageId)

Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.

Files.GetAttachment(attachmentId)

Downloads a single attachment. Simply supply the unique identifier for the required attachment.

Analysis

Analysis.Spam(messageId)

Perform spam testing on the specified email.