# How to test email and SMS in .NET Learn how to automate testing of 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](/app/signup). ## 2. Create a sample project ### Install .NET To see if you already have .NET installed, open a terminal window and run this command: ```bash dotnet --version ``` If .NET is installed, you’ll see a version number. If you see an error instead, then [download .NET from Microsoft](https://dotnet.microsoft.com/en-us) and install it. ### Create a new project Run each of these commands to create a new .NET project: ```bash mkdir EmailTests cd EmailTests dotnet new console ``` ### Install the Mailosaur .NET library Run this command to install the [Mailosaur NuGet package](https://github.com/mailosaur/mailosaur-dotnet): ```bash dotnet add package mailosaur ``` ## 3. Send email to your Mailosaur inbox Inboxes allow you to group tests, permissions, and other settings together. Each inbox has an **Inbox ID** and 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](/docs/managing-your-account/api-keys) to use. You can learn more about [creating API keys here](/docs/managing-your-account/api-keys). ### Retrieve your inbox’s attributes 1. In the left-hand navigation, locate the **Inboxes** section. 2. Click on the name of the inbox you want to test with. 3. Click the **Settings** tab. 4. Make a note of the **Inbox ID** and **Domain**. 5. Get an API key from the [API Keys](/app/keys) page. ### Send an email to your inbox If the **domain name** of your inbox above was: ```bash 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. In the left-hand navigation, locate the **Inboxes** section. 3. Click on the name of the inbox 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](/docs/email-testing/sending-to-mailosaur). ## 4. Find an email for automated testing Now that you have a sample project, your inbox’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: ```csharp using System; using Mailosaur; using Mailosaur.Models; namespace EmailTests { class Program { static void Main(string[] args) { // Find these on the API Keys page and your inbox's Settings tab 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: ```bash dotnet run ``` If everything is set up correctly, you should see the subject line of the last email you sent, printed to screen: ```bash 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. Narrowing your search results ### Only find messages received after a certain time By default, searches include messages received in the last hour, but you can customise the search window with the `receivedAfter` option. This example shows you how to only include emails received after your test started: ```csharp var testStart = DateTime.UtcNow; // Perform the steps that send a message here var criteria = new SearchCriteria() { SentTo = "..." }; var message = mailosaur.Messages.Get( "SERVER_ID", criteria, receivedAfter: testStart ); ``` ### Search criteria As you can see in the examples so far, you can search for the email address or phone number a message was sent to, but you can also search using these criteria: | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **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** | Find emails where the subject line contains this text. | | **Body** | Finds messages where the message body contains this text. | ## 6. 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: > [!LINK](/docs/automation/text-content) > ### How to test the text content of email or SMS > Learn how to test the text content of email or SMS with Mailosaur. > [!LINK](/docs/automation/html-content) > ### HTML content of an email > Learn how to work with the HTML content found within your emails. > [!LINK](/docs/automation/codes) > ### Extracting codes from email and SMS > Learn how to test verification codes found in email and SMS messages with Mailosaur. > [!LINK](/docs/automation/links) > ### Extracting links from email and SMS > Learn how to test hyperlinks found in email and SMS messages with Mailosaur. > [!LINK](/docs/automation/attachments) > ### Email attachments > Learn how to test the email attachments with Mailosaur. > [!LINK](/docs/automation/images) > ### Images and web beacons > Learn how to work with images, including web beacons, within an HTML email. > [!LINK](/docs/automation/message-properties) > ### Message properties > Learn how to test the common properties of an email or SMS message with Mailosaur. > [!LINK](/docs/automation/spam) > ### How to test email spam score > Learn how to test the SpamAssassin score of an email with Mailosaur. ## SMS Testing You can test SMS messages in much the same way as email. Take a look at our [guide on testing SMS messages](/docs/sms-testing) for more information. ## 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](/docs/api) 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. ```csharp var message = mailosaur.Messages.Get("SERVER_ID", new SearchCriteria() { SentTo = "someone@SERVER_ID.mailosaur.net" }); ``` To learn about inbox IDs, and what to replace `SERVER_ID` with, see [sending email to Mailosaur](/docs/email-testing/sending-to-mailosaur). ##### Criteria | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **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 | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **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_). | ```csharp // Search all messages received after midnight on a specific 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. > [!SUCCESS] > 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`](#messagesgetbyidid). Alternatively, we recommend using the [`Get`](#messagesgetserver-criteria-options) method, which is a far more efficient approach. ```csharp // 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. - **dir** Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. ```csharp // List all results received after midnight on a specific date // 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. > [!SUCCESS] > 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`](#messagesgetbyidid). Alternatively, we recommend using the [`Get`](#messagesgetserver-criteria-options) method, which is a far more efficient approach. ```csharp 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 | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **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 | PARAMETER | DESCRIPTION | | ------------ | ------------ | | **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 thrown 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. | | **dir** | Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`. | ```csharp // Search for all messages sent to someone@SERVER_ID.mailosaur.net, // received after midnight on a specific date. 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`](#messageslistserver-options) or [`Search`](#messagessearchserver-criteria-options) in order to get the unique identifier for the required message. **We always recommend using the** [`Get`](#messagesgetserver-criteria-options) **method instead**. ```csharp 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. ```csharp mailosaur.Messages.Delete(messageId); ``` #### Messages.DeleteAll(server) Permanently deletes all messages held in the specified inbox. Also deletes any attachments related to each message. This operation cannot be undone. ```csharp mailosaur.Messages.DeleteAll("SERVER_ID"); ``` #### Messages.Create(server, messageCreateOptions) Creates a new message that can be sent to a verified email address. This is useful in scenarios where you want an email to trigger a workflow in your product. ```csharp mailosaur.Messages.Create("SERVER_ID", new MessageCreateOptions() { To = "verified-address@example.com", Send = true, Subject = "Request" Text = "Please can you give us a call back?" }); ``` ##### Options - **to** The email address to which the email will be sent. Must be a verified email address. - **send** If true, email will be sent upon creation. - **subject** The email subject line. - **text** The plain text body of the email. - **html** The HTML body of the email. #### Messages.Forward(messageId, messageForwardOptions) Forwards the specified email to a verified email address. ```csharp mailosaur.Messages.Forward("MESSAGE_ID", new MessageForwardOptions() { To = "verified-address@example.com", Text = "FYI" }); ``` ##### Options - **to** The email address to which the email will be sent. Must be a verified email address. - **text** Any additional plain text content to forward the email with. - **html** Any additional HTML content to forward the email with. #### Messages.Reply(messageId, messageReplyOptions) Sends a reply to the specified email. This is useful for when simulating a user replying to one of your emails. ```csharp mailosaur.Messages.Reply("MESSAGE_ID", new MessageReplyOptions() { Text = "FYI" }); ``` ##### Options - **text** Any additional plain text content to include in the reply. - **html** Any additional HTML content to include in the reply. ### Servers Inboxes capture emails and SMS messages, group your tests and settings, and manage access for your team. #### Servers.List() Returns a list of your inboxes. Inboxes are returned sorted in alphabetical order. ```csharp ServerListResult result = mailosaur.Servers.List(); Console.WriteLine("You have an inbox called: " + result.Items[0].Name); ``` #### Servers.Create(server) Creates a new inbox. Only the `name` property is required to create a new inbox via the API. ```csharp var options = new ServerCreateOptions("My email tests"); mailosaur.Servers.Create(options); ``` #### Servers.Get(id) Retrieves the detail for a single inbox. Simply supply the unique identifier for the required inbox. ```csharp var server = mailosaur.Servers.Get("SERVER_ID"); ``` #### Servers.GetPassword(id) Retrieves the password, for use with SMTP and POP3, for a single inbox. Simply supply the unique identifier for the required inbox. ```csharp var password = mailosaur.Servers.GetPassword("SERVER_ID"); ``` #### Servers.Update(id, server) Updates a single inbox. ```csharp var retrievedServer = mailosaur.Servers.Get("SERVER_ID"); retrievedServer.Name = "Updated inbox name"; mailosaur.Servers.Update(retrievedServer.Id, retrievedServer); ``` #### Servers.Delete(id) Permanently deletes an inbox. Also deletes all messages and associated attachments within the inbox. This operation cannot be undone. ```csharp mailosaur.Servers.Delete("SERVER_ID"); ``` #### Servers.GenerateEmailAddress(id) Utility method to help you generate a random email address for a given inbox. ```csharp var emailAddress = mailosaur.Servers.GenerateEmailAddress("SERVER_ID"); Console.WriteLine(emailAddress); // "bgwqj@SERVER_ID.mailosaur.net" ``` To learn about inbox IDs, and what to replace `SERVER_ID` with, see [sending email to Mailosaur](/docs/email-testing/sending-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. ### Usage #### Usage.Limits() Retrieve account usage limits. Details the current limits and usage for your account. This endpoint requires authentication with an account-level API key. #### Usage.Transactions() Retrieves the last 31 days of transactional usage. This endpoint requires authentication with an account-level API key.