Library Reference

The Mailosaur .NET library lets you integrate email and SMS testing into your continuous integration process.

This guide provides details on all the methods available within the library.

To check out some common use cases, take a look at getting started with .NET.

Getting started

Install the Mailosaur .NET Library

Install via NuGet:

From the command line:

nuget install mailosaur

From Package Manager:

PM> Install-Package mailosaur

From within Visual Studio:

  1. Open the Solution Explorer.
  2. Right-click on a project within your solution.
  3. Click on Manage NuGet Packages…
  4. Click on the Browse tab and search for “Mailosaur”.
  5. Click on the Mailosaur package, select the appropriate version in the right-tab and click Install.

‘Hello world’

To use the library, simply add it as a dependency and create a client instance using your API key. You can then use any of the methods described in this document.

To try this out, create a simple ‘hello world’ program with the following code inside it:

using System;
using Mailosaur;

namespace dotnet
{
  class Program
  {
    static void Main(string[] args)
    {
      var mailosaur = new MailosaurClient("YOUR_API_KEY");

      var result = mailosaur.Servers.List();

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

Just replace YOUR_API_KEY with the your API key, then run the example. If everything is set up correctly, you should see a server name printed out.

Using a test framework

It’s more likely that you are using a testing framework, like XUnit. In this case, the concept is still very much the same:

using Xunit;
using Mailosaur;
using Mailosaur.Models;

namespace dotnet_test
{
  public class UnitTest1
  {
    private MailosaurClient mailosaur = new MailosaurClient("YOUR_API_KEY");

    [Fact]
    public void TestPasswordReset()
    {
      var server = "SERVER_ID";

      // 1. Generate a unique email address for this test
      var emailAddress = mailosaur.Servers.GenerateEmailAddress(server);

      // 2. **Your automation code that triggers an email to `emailAddress`**

      // 3. Wait for email to arrive at the target email address
      var email = mailosaur.Messages.Get(server, new SearchCriteria() {
        SentTo = emailAddress
      });

      // 4. Perform assertions on the email
      Assert.Equal("Set a new password", email.Subject);
    }
  }
}

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

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.

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

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

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.

Options

  • 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 20 seconds ago).
// Search all messages received after midnight 5th Jan 2020
var message = mailosaur.Messages.Get("SERVER_ID", new SearchCriteria() {
  SentTo = "someone.SERVER_ID@mailosaur.io"
}, 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.io"
});

// 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.io,
// 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.io"
}, 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.io"

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.