Forem: MailSlurp

Testing OTP codes in Selenium with dummy authenticators

MailSlurp — Wed, 11 Jun 2025 23:43:35 +0000

Secure application are often a complex process involving multiple factors of authentication. Many developers use services like Auth0, Firebase and Azure AD/Entra to build user login and sign up flows that connect applications to enterprise IdPs using MFA and 2FA flows. These methods often involve receiving verification codes and time-based one-time passwords (TOTP) to verify accounts.

Hint: TOTP stands for time-based one-time password. You might have used TOTP with Google Authenticator or Duo on a mobile device.

With strict compliance and regulatory requirements testing these apps end-to-end is crucial. This requires special QA techniques and disposable authenticator devices which we will demonstrate in this post. For this example we will use Selenium and Java but the methods for testing TOTP passcodes apply to any integration testing framework.

What we are testing

Let's test a typical MFA authentication flow that uses an Auth0 integration and time-based one-time pass codes to sign-up and verify user accounts. The process looks like this:

We have a basic VueJS app that uses the Auth0 vue library to launch the authentication flow and handle the user authentication. The process is as follows:

User opens the Vue application and navigates to the sign-up page.
User enters their email and password to create a new account.
Application prompts the user to set up MFA (TOTP).
Auth0 displays a QR code for TOTP configuration.
User scans the QR code with an authenticator app (or test device).
User enters the generated TOTP code to verify setup.
Upon successful verification, the user is logged in and MFA is enabled for future logins.

Note you can find all the code for this example on Github

Testing requirements

In order to test this reliably and without manual intervention we will need:

Disposable user email accounts
Virtual MFA Authenticators

Luckily, MailSlurp is a free service that provides all these and more. We can use the official MailSlurp Java SDK to create email accounts and generate new OTP codes that work seamlessly with IdPs like Auth0.

How to test OTP in Selenium

Okay let's get started. We assume you have a selenium Java project setup up in maven and the necessary drivers installed. In order to create email accounts and TOTP devices for this test we will also need the mailslurp-client-java library we can obtain from maven central.

Install MailSlurp

For maven, add to your pom.xml:

<dependency>
    <groupId>com.mailslurp</groupId>
    <artifactId>mailslurp-client-java</artifactId>
    <version>16.2.1</version>
</dependency>

For Gradle add the following:

implementation group: 'com.mailslurp', name: 'mailslurp-client-java', version: '16.2.1'

Note: MailSlurp is free, you just need to create an API KEY

We can then import MailSlurp in our tests like so:

import com.mailslurp.apis.InboxControllerApi;
import com.mailslurp.apis.MfaControllerApi;
import com.mailslurp.clients.ApiClient;
import com.mailslurp.clients.ApiException;
import com.mailslurp.models.CreateInboxDto;
import com.mailslurp.models.CreateTotpDeviceOtpAuthUrlOptions;

Open app and begin login

Great, now for our test. The first step will be to open our demo application that has the Auth0 library installed. This app will begin the MFA flow that asks for a TOTP code.

// navigate to our test app that uses Auth0 MFA for authentication
driver.get(APP_URL);
String body = wait.until(visibilityOfElementLocated(By.tagName("body"))).getText();
assertTrue(body.contains("Login"), "Expect home page");

Once opened we click the login button:

// click new sign up
wait.until(elementToBeClickable(By.id("qsLoginBtn"))).click();
wait.until(elementToBeClickable(By.cssSelector("a[href^='/u/signup']"))).click();

Create an isolated test account

In order to sign-up we need an email address. Let's create one in MailSlurp. This will be a real disposable email account that can send and receive emails.

// setup mailslurp api client
var apiClient = new ApiClient();
apiClient.setApiKey(MAILSLURP_API_KEY);

// create disposable email account
var inboxController = new InboxControllerApi(apiClient);
var inbox = inboxController.createInboxWithOptions(new CreateInboxDto().expiresIn(300_000L)).execute();
String emailAddress = inbox.getEmailAddress();
String password = "testPassword123!";

Fill sign-up form

Once we have an email account we use it to fill out the username. Next we add a randomized password and click submit.

// fill in the sign up form and submit
wait.until(visibilityOfElementLocated(By.id("email"))).sendKeys(emailAddress);
wait.until(visibilityOfElementLocated(By.id("password"))).sendKeys(password);

wait.until(elementToBeClickable(By.cssSelector("button[type='submit']"))).click();

Once filled the app will look like this:

After submitting the sign-up we will see a QR code in order to attach a TOTP device:

Extract OTPAuth url

A MFA TOTP connection typically involves a QR code that has a special link encoded in it. This link follows a pattern like:

otpauth://totp/dev-28vff4a6lyu4gize:contact%40mailslurp.dev?secret=LJCTOYKGGBAWCMSHJRZGITCVLIXCG4JY&issuer=dev-28vff4a6lyu4gize&algorithm=SHA1&digits=6&period=30

Notice the optauth:// schema. The rest of the URL contains various elements but the most important is the secret. This is a base32 encoded secret that allows the TOTP device to generate codes. In our test application we can extract the full OTP Auth url by reading it from the dom. Auth0 adds a special data attribute that contains this value:

We can extract this code like this:

// expect MFA QR code to be displayed then extract the otpauth:// URI from the QR code
wait.until(visibilityOfElementLocated(By.cssSelector("[data-qr-data]")));
String optAuthUrl = driver.findElement(By.cssSelector("[data-qr-data]")).getAttribute("data-qr-data");
assertTrue(optAuthUrl.startsWith("otpauth://"), "Expect otpauth:// URI in QR code");

Note: If you can't see the OTP Auth URL in the dom you can use various other methods to connect the TOTP device (including passing a secret directly, passing a screenshot of the QR code, or the QR code image source). See the TOTP docs

Create virtual TOTP device

Now we need to use an authenticator device for our user to verify the account. We will use MailSlurp to generate an TOTP device using the OTP auth url:

// next create a TOTP authenticator device in MailSlurp
var mfaController = new MfaControllerApi(apiClient);
var virtualTotpDevice = mfaController.createTotpDeviceForOtpAuthUrl(new CreateTotpDeviceOtpAuthUrlOptions()
        // pass the QR code otpauth:// URI to MailSlurp
        .otpAuthUrl(optAuthUrl)
).execute();

This device will let us generate valid confirmation codes for submitting to the app.

Generate time based one time password

Next we can generate a valid OTP code using the SDK. This code will be valid for a short time as specified in the arguments. We need to then submit it to Auth0 to finish the sign-up:

// now generate a secret code from the TOTP device and submit it
var oneTimeCode = mfaController.getTotpDeviceCode(virtualTotpDevice.getId())
        // ensure code is valid long enough to be entered by selenium
        .minSecondsUntilExpire(10)
        .execute().getCode();
wait.until(visibilityOfElementLocated(By.id("code"))).sendKeys(oneTimeCode);

// submit the code
wait.until(elementToBeClickable(By.cssSelector("button[data-action-button-primary=\"true\"]"))).click();

wait.until(elementToBeClickable(By.cssSelector("button[name='action'][value='accept']"))).click();

The submission looks like this:

And afterwards we need to accept the connection:

Assert account is verified

Voila! Now we have a logged in user with a connected MFA device. We can assert that by checking the user profile:

// expect login home page and email address in the profile dropdown
wait.until(elementToBeClickable(By.id("profileDropDown"))).click();
wait.until(visibilityOfElementLocated(By.cssSelector("#profileDropDown + .dropdown-menu")));
String dropdownText = driver.findElement(By.cssSelector("#profileDropDown + .dropdown-menu")).getText();

assertTrue(dropdownText.contains(emailAddress), "Dropdown menu should contain the email address");

Here is a screenshot:

Testing logout / login

Now that our full sign-up is complete we can also test the logout and login process to check that the MFA TOTP connection functions:

// click logout
wait.until(elementToBeClickable(By.id("qsLogoutBtn"))).click();
// then try login again
wait.until(elementToBeClickable(By.id("qsLoginBtn"))).click();
wait.until(visibilityOfElementLocated(By.id("username"))).sendKeys(emailAddress);
wait.until(visibilityOfElementLocated(By.id("password"))).sendKeys(password);
wait.until(elementToBeClickable(By.cssSelector("button[data-action-button-primary=\"true\"]"))).click();
// expect to see MFA code entry field again after login
wait.until(visibilityOfElementLocated(By.id("code")));

Once we log in with the email and password we generated we can see the MFA prompt asking for a new code. Using the same TOTP device we can generate that code and submit it:

// get another TOTP code from the same device and submit it to complete login
var oneTimeCode2 = mfaController.getTotpDeviceCode(virtualTotpDevice.getId())
        .minSecondsUntilExpire(10)
        .execute().getCode();
wait.until(visibilityOfElementLocated(By.id("code"))).sendKeys(oneTimeCode2);
wait.until(elementToBeClickable(By.cssSelector("button[data-action-button-primary=\"true\"]"))).click();
// expect logged in screen again
wait.until(elementToBeClickable(By.id("profileDropDown"))).click();
wait.until(visibilityOfElementLocated(By.cssSelector("#profileDropDown + .dropdown-menu")));
String dropdownText2 = driver.findElement(By.cssSelector("#profileDropDown + .dropdown-menu")).getText();
assertTrue(dropdownText2.contains(emailAddress), "Dropdown menu should contain the email address");

Conclusion

We just demonstrated how to test a multifactor authentication user flow using Selenium and MailSlurp's free test TOTP API. Using dummy authenticator devices is a great way to verify security compliance and app functionality in QA and automation environments.

To add MFA testing to your own application or IdP see the documentation or connect with our team.

How to test Spring views using Playwright and SpringBootTest in Kotlin and Java

MailSlurp — Wed, 25 Oct 2023 00:08:50 +0000

In today's agile development landscape, testing your web application thoroughly is more important than ever. A toolset that facilitates quick and reliable testing can be a developer's best friend. This is where integrating Playwright, a powerful browser automation library, with your SpringBoot application comes into play.

In this blog post, we delve deep into how you can leverage the capabilities of Playwright browsers to write robust tests for your SpringBoot HTML endpoints. Whether you are a seasoned developer or just getting started with SpringBoot, this guide will walk you through the steps to test your Spring views seamlessly using Playwright and the SpringBootTest annotation.

Get ready to enhance the stability and reliability of your web application by integrating the prowess of Playwright into your testing regimen.

What is Playwright?

Playwright is a tool from Microsoft that enables browser automation and testing. Java developers can utilize Playwright to script multi-browser tests with a modern and fluent API design, enjoying perks like automatic waiting, efficient selectors, and seamless handling of iframes and pop-ups, which can notably reduce the flakiness often associated with browser tests.

Why no Selenium

In comparison, Selenium, a well-established tool in the Java world, might be familiar ground for many developers, offering wide-ranging browser support and a vast array of community-driven plugins and integrations. However, it sometimes falls short in speed and requires more boilerplate code, making tests less concise.

Manual testing

Furthermore, when we bring manual testing into the picture, the advantages of tools like Playwright become even more apparent. Manual testing, although necessary in certain contexts, can be time-consuming and prone to human error. Automating your testing process with Playwright not only expedites the testing cycle but also ensures a higher degree of accuracy and reliability, fostering a more agile and responsive development workflow. Thus, Playwright stands as a modern alternative that can complement or even replace Selenium and manual testing methodologies, pushing towards a more streamlined and efficient testing approach in the Java ecosystem.

Writing a test

In this post we will test an endpoint that renders HTML forms. We will use SpringBootTest and Playwright to load the page and make assertions.

Spring boot setup

Assuming you have an existing Spring boot application, create a test file. Our initial scaffold will look like this. Note we are using Kotlin in this post but you can use Java without any problems.

package browser

import org.junit.jupiter.api.extension.ExtendWith
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.context.ActiveProfiles
import org.springframework.test.context.junit.jupiter.SpringExtension


@ExtendWith(SpringExtension::class)
@SpringBootTest(
      webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT
)
@UseEmbeddedPostgres
class AdminBrowserTest {
    @LocalServerPort
    private int port;
}

We use a RANDOM_PORT environment here so we can map the server's port using @LocalServerPort. This will come in handy when we want to load the server pages in Playwright.

Installing Playwright

For maven users add this to your pom.xml:

<dependencies>
    <dependency>
        <groupId>com.microsoft.playwright</groupId>
        <artifactId>playwright</artifactId>
        <version>1.37.0</version>
    </dependency>
</dependencies>

For gradle add the testImplementation:

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'com.microsoft.playwright:playwright:1.37.0'
}

Adding Playwright

Next we can import Playwright and AssertJ into our tests:

import com.microsoft.playwright.Browser;
import com.microsoft.playwright.BrowserContext;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;
import org.assertj.core.api.Assertions.assertThat

Now we can create a playwright browser instance for each test case:

companion object {
    // Shared between all tests in this class.
    var playwright: Playwright? = null
    var browser: Browser? = null

    // New instance for each test method.
    var context: BrowserContext? = null
    var page: Page? = null

    @JvmStatic
    @BeforeAll
    fun launchBrowser() {
        playwright = Playwright.create()
        browser = playwright!!.chromium().launch()
    }

    @AfterAll
    @JvmStatic
    fun closeBrowser() {
        playwright!!.close()
    }
}

@BeforeEach
fun createContextAndPage() {
    context = browser.newContext()
    page = context.newPage()
}

@AfterEach
fun closeContext() {
    context.close()
}

@Test
fun `can load index` () {
    page.navigate("http://localhost:$port")
    assertThat(page.waitForSelector("h1").innerText()).contains("MailSlurp")
}

Conclusion

In conclusion, integrating Playwright as a testing tool for your Spring Boot application in Java offers practical benefits. Playwright facilitates a straightforward and effective testing process, allowing for easy automation of browser actions, which can be a substantial time-saver compared to manual testing methods. Its modern API design enables concise and maintainable test scripts, which can potentially simplify the codebase and reduce maintenance efforts.

Compared to other testing tools like Selenium, Playwright often offers faster execution times and more reliable test runs, helping to speed up the development cycle without sacrificing quality. Its compatibility with Spring Boot ensures that developers can leverage its features without any significant adjustments to their existing setups.

Overall, incorporating Playwright into your Spring Boot project represents a logical step towards enhancing the efficiency and reliability of your application's testing procedures, making it a valuable addition to your Java project's testing toolkit.

Extending tests with email

In automated testing, ensuring the correct functioning of email services within your application is crucial. Combining Playwright with the MailSlurp Java client can streamline this process remarkably.

With MailSlurp, you can create and manage email addresses dynamically to send and receive emails during your tests, allowing for real-time verification of email functionalities within your application.

Meanwhile, Playwright can be used to automate browser interactions, including actions triggered by received emails, such as clicking verification links or resetting passwords.

Together, Playwright and MailSlurp can work in harmony to create a comprehensive testing environment where both web interactions and email communications can be tested seamlessly and effectively, enhancing the reliability and robustness of your application.

Email in Laravel with Mailable & Notification classes (and how to test them in Dusk!)

MailSlurp — Wed, 14 Jun 2023 06:47:52 +0000

Laravel is a very popular PHP framework with the built-in ability to send email. This tutorial demonstrates how to use two different email techniques in Laravel to send mail: Mailable and Notification. It then shows how to test that emails are sent correctly using Dusk and MailSlurp fake mail catchers.

Tutorial basics

To illustrate email sending in Laravel let us create a demo app that allows users to sign up for a newsletter using a form and select to be emailed using Mailable or Notification techniques. We will then write Dusk browser tests using Chrome and MailSlurp disposable email addresses to capture the outbound email and verify the results. This is what our project will look like:

When the user visits our site they will be given the choice to sign up to receive an email newsletter. For demonstration purposes we'll make two implementations, one using Mailable and another using Notifications. Full code can be found on the github examples repository.

Notifcations vs Mailable

Laravel provides two primary ways to send notifications to users: Mailables and Notifications. Here's a brief comparison:

Aspect	Mailables	Notifications
Purpose	Designed specifically for email communication	Designed for quick, simple messages that can be sent via various channels
Customization	Provides flexibility for complex email layouts and designs	Offers customization focused on the message content rather than design
Delivery channels	Restricted to the email channel	Supports multiple channels, including mail, database, broadcast, SMS (via Nexmo), and Slack
Queue	Can be queued for background sending	Can also be queued for background sending
Complexity	Might be a bit more complex to set up initially, especially with complex designs	Typically simpler to set up, particularly if you're using multiple channels

Notifications and Mailables both have their uses. In this post we will show to how use and test both of them.

Setting up a project

Let's assume you have an existing Laravel project with composer. If not create one with:

php composer.phar create-project laravel/laravel php-laravel-phpunit

Then add the MailSlurp library so we can use email addresses. You need an API Key so create a free account to obtain one:

php composer.phar require --dev mailslurp/mailslurp-client-php

Then configure dusk to enable browser testing:

php composer.phar require --dev laravel/dusk
php artisan dusk:install
php artisan dusk:chrome-driver --detect

We can add a basic welcome page with a link to our two different sign up methods (Mailable and Notification):

The buttons link to /newsletter and /notification respectively.

Configure mail settings

Before we can send emails we need to configure PHP mail settings. Laravel sends email using an external SMTP mailserver. We can configure this inside .env or config/mail.php.

Using .env

If you have created an inbox in MailSlurp then you can use the SMTP access details provided in the MailSlurp dashboard to configure the SMTP credentials inside .env

MAIL_MAILER=smtp
MAIL_HOST=mailslurp.mx
MAIL_PORT=2587
MAIL_USERNAME=your-smtp-username
MAIL_PASSWORD=your-smtp-password
MAIL_FROM_ADDRESS="your-inbox@mailslurp.com"

The disadvantage of this approach is that the settings are static. For this example we will use config/mail.php instead which allows dynamic configuration.

Using config/mail.php

For this example we want to use create and use a new MailSlurp inbox for sending within the app. We can use the MailSlurp API client inside mail.php to configure these settings:

// configure mailslurp client
$config = MailSlurp\Configuration::getDefaultConfiguration()->setApiKey('x-api-key', $MAILSLURP_API_KEY);

// create an inbox to send emails from
$inboxController = new MailSlurp\Apis\InboxControllerApi(null, $config);
$senderInbox = $inboxController->createInboxWithOptions(new \MailSlurp\Models\CreateInboxDto(['inbox_type' => 'SMTP_INBOX', 'name' => 'Newsletters']));
$accessOptions = $inboxController->getImapSmtpAccess($senderInbox->getId());

// get access to the inbox
$host = $accessOptions->getSecureSmtpServerHost();
$port = $accessOptions->getSecureSmtpServerPort();
$username = $accessOptions->getSecureSmtpUsername();
$password = $accessOptions->getSecureSmtpPassword();

// configure laravel mailer settings to use our sender inbox
// for production apps set this in .env instead with static values
// make sure you run `API_KEY=$(API_KEY) php artisan config:cache` after setting
return [
    'default' => 'smtp',
    'mailers' => [
        'smtp' => [
            'transport' => 'smtp',
            'url' => env('MAIL_URL'),
            'host' => $host,
            'port' => $port,
            'encryption' => 'tls',
            'username' => $username,
            'password' => $password,
            'timeout' => null,
            'local_domain' => env('MAIL_EHLO_DOMAIN'),
        ],
    ],
    'from' => [
        'address' => $senderInbox->getEmailAddress(),
        'name' => $senderInbox->getName(),
    ],
    'markdown' => [
        'theme' => 'default',
        'paths' => [
            resource_path('views/vendor/mail'),
        ],
    ],
];

Note that each time you change the config you need to run:

php artisan config:cache

Create a Mailable

To send email using Mailables we can scaffold a class:

php artisan make:mail Newsletter

Inside the class we define which view we will use:

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class Newsletter extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * Get the message envelope.
     */
    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Newsletter',
        );
    }

    /**
     * Get the message content definition.
     */
    public function content(): Content
    {
        return new Content(
            view: 'emails.newsletter',
        );
    }
}

For the view we used emails.newsletter - this means we need to define a blade template view in resources/views/emails/newsletter:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Welcome Email</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@1/css/pico.min.css">
</head>
<body>
<h1>Welcome to our newsletter!</h1>
<p>We are glad you have decided to join us.</p>
</body>
</html>

This view will be used as the email body when we send using the Mailable class.

Define a Notification

For the Notification approach we can do something similar using Notification classes

php artisan make:notification NewsletterNotification

The class looks like so:

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;

class NewsletterNotification extends Notification
{
    use Queueable;

    public function __construct()
    {
    }

    public function via(object $notifiable): array
    {
        // use mail to send
        return ['mail'];
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->line('Welcome to our notifications!')
            ->line('We are glad you have decided to use notifications.');
    }
}

Notice here we don't use a view. This is because laravel will style our notifications for us. This is a major difference between Mailables and Notifications.

Create controller routes

We want users to sign up with email addresses for a fake newsletter. Let's use artisan to create controllers and routes for each method:

php artisan make:controller NewsLetter
php artisan make:controller Notification

We will show a form on each page so let's wire up the routes:

Route::get('/newsletter', [NewsletterController::class, 'create']);
Route::post('/newsletter', [NewsletterController::class, 'store']);
Route::get('/notification', [NotificationController::class, 'create']);
Route::post('/notification', [NotificationController::class, 'store']);

Define controllers

So we have defined our routes and mail config. Now let's create a controller for each method.

Mailable controller

For the mailable use we need a form with an email input like this:

Let's define the view:

@extends('layout', ['logo' => '/newsletter.svg'])
@section('content')
<div class="scale-100 p-6 bg-white dark:bg-gray-800/50 dark:bg-gradient-to-bl from-gray-700/50 via-transparent
dark:ring-1 dark:ring-inset dark:ring-white/5 rounded-lg shadow-2xl shadow-gray-500/20 dark:shadow-none flex transition-all duration-250 focus:outline focus:outline-2 focus:outline-red-500">
    <div>
        <h2 class="text-xl font-semibold text-gray-900 dark:text-white">Enter your newsletter details</h2>

        <p class="mt-4 text-gray-500 dark:text-gray-400 text-sm leading-relaxed">
            We will email you every Sunday with the latest Laravel news.
        </p>
        <div class="mt-4">
            <form class="flex flex-col gap-4" method="POST" action="/newsletter" data-test-id="newsletter-form">
                @csrf
                <label>
                    <input type="email" id="email" name="email" required placeholder="Your email address..." class="appearance-none rounded p-2 w-full">
                </label>
                <button type="submit" id="submit" class="rounded bg-red-500 text-white p-2 px-4">Sign up</button>
            </form>
        </div>
    </div>
</div>
@endsection

The important part here is the form and input. We also need a view for when the form is successfully submitted:

@extends('layout', ['logo' => '/success.svg'])
@section('content')
<div class="scale-100 p-6 bg-white dark:bg-gray-800/50 dark:bg-gradient-to-bl from-gray-700/50 via-transparent
dark:ring-1 dark:ring-inset dark:ring-white/5 rounded-lg shadow-2xl shadow-gray-500/20 dark:shadow-none flex transition-all duration-250 focus:outline focus:outline-2 focus:outline-red-500">
    <div>
        <h2 class="text-xl font-semibold text-gray-900 dark:text-white">Thanks!</h2>

        <p class="mt-4 text-gray-500 dark:text-gray-400 text-sm leading-relaxed" data-test-id="newsletter-success">
            We have saved your email address <span class="font-semibold" data-test-id="email-result">{{$email}}</span>
        </p>
    </div>
</div>
@endsection

This will thank the user after submission. Next we need to wire up the views with our controller and configure the Mailable call:

namespace App\Http\Controllers;

use App\Mail\Newsletter;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;

class NewsletterController extends Controller
{
    public function create()
    {
        return view('newsletter');
    }

    public function store(Request $request)
    {
        // get the email from the form submission
        $email = $request->validate(['email' => 'required|email']);

        // send an email to the user using the Newsletter Mailable
        Mail::to($email['email'])->send(new Newsletter($email['email']));

        return view('newsletter-success', ['email' => $email['email']]);
    }
}

This configuration allows the user to submit the newsletter form and be emailed using a Mailable. After that we render the success form.

Notification controller

We can also do the same using Notifications. Here we need a similar form with views and controller:

@extends('layout', ['logo' => '/notification.svg'])
@section('content')
<div class="scale-100 p-6 bg-white dark:bg-gray-800/50 dark:bg-gradient-to-bl from-gray-700/50 via-transparent
dark:ring-1 dark:ring-inset dark:ring-white/5 rounded-lg shadow-2xl shadow-gray-500/20 dark:shadow-none flex transition-all duration-250 focus:outline focus:outline-2 focus:outline-red-500">
    <div>
        <h2 class="text-xl font-semibold text-gray-900 dark:text-white">Enter your notification details</h2>

        <p class="mt-4 text-gray-500 dark:text-gray-400 text-sm leading-relaxed">
            We will notify you whenever something exciting happens
        </p>
        <div class="mt-4">
            <form class="flex flex-col gap-4" method="POST" action="/notification" data-test-id="notification-form">
                @csrf
                <label>
                    <input type="email" id="email" name="email" required placeholder="Your email address..." class="appearance-none rounded p-2 w-full">
                </label>
                <button type="submit" id="submit" class="rounded bg-red-500 text-white p-2 px-4">Enable notifications</button>
            </form>
        </div>
    </div>
</div>
@endsection

The success page will look like this:

@extends('layout', ['logo' => '/success.svg'])
@section('content')
<div class="scale-100 p-6 bg-white dark:bg-gray-800/50 dark:bg-gradient-to-bl from-gray-700/50 via-transparent
dark:ring-1 dark:ring-inset dark:ring-white/5 rounded-lg shadow-2xl shadow-gray-500/20 dark:shadow-none flex transition-all duration-250 focus:outline focus:outline-2 focus:outline-red-500">
    <div>
        <h2 class="text-xl font-semibold text-gray-900 dark:text-white">Thanks!</h2>

        <p class="mt-4 text-gray-500 dark:text-gray-400 text-sm leading-relaxed" data-test-id="notification-success">
            We have saved your email address <span class="font-semibold" data-test-id="email-result">{{$email}}</span>
        </p>
    </div>
</div>
@endsection

Next we configure the views inside the Notification controller and use the NewsletterNotification class to email the user:

namespace App\Http\Controllers;

use App\Notifications\NewsletterNotification;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Notification;

class NotificationController extends Controller
{
    public function create()
    {
        return view('notification');
    }

    public function store(Request $request)
    {

        // get the email from the form submission
        $email = $request->validate(['email' => 'required|email']);

        // send an email to the user using the Newsletter Notification
        Notification::route('mail', $email['email'])
            ->notify(new NewsletterNotification());

        return view('notification-success', ['email' => $email['email']]);
    }
}

This configures views for submission and success:

Testing the application with Dusk

So now we have created routes, views, and controllers for Mailable and Notification methods. Next we want to define two browser tests that will:

Load the welcome page in a browser
Click on each link
Create a disposable email address
Submit the email address for newsletter sign-up
Verify that the email is sent and received

What is Dusk?

The most common way to test Laravel applications end-to-end with real browsers is Dusk. Dusk uses Chromedriver to instantiate a headless chrome browser and control it remotely. You can define tests in PHP and assert that our application is functioning correctly.

How does MailSlurp integrate?

The reason for using MailSlurp is that it lets us create throwaway email accounts during tests and use them to sign up and receive emails. We can also use the MailSlurp PHP client to wait for the sent emails and fetch them for verification.

Create Dusk tests

public function testNewsletterMailable(): void
{

    $this->browse(function (Browser $browser) {
        $MAILSLURP_API_KEY = env('API_KEY');
        // configure mailslurp client
        $config = MailSlurp\Configuration::getDefaultConfiguration()->setApiKey('x-api-key', $MAILSLURP_API_KEY);
        $inboxController = new MailSlurp\Apis\InboxControllerApi(null, $config);

        // create a disposable email address
        $inbox = $inboxController->createInboxWithDefaults();

        // load the app in the browser
        $browser->resize(1440, 900);
        $browser->visit('http://localhost:8000/')
            ->assertSee('Sign up for our newsletter');
        $browser->screenshot('welcome');

        // click the newsletter link
        $browser->click('[data-test-id="newsletter-link"]');
        $browser->waitFor('[data-test-id="newsletter-form"]');
        $browser->screenshot('newsletter-form');

        // fill the newsletter sign up form with the disposable email address
        $browser->type('#email', $inbox->getEmailAddress());
        $browser->screenshot('newsletter-form-filled');
        $browser->click('#submit');

        // submit the form and see a success message
        $browser->waitFor('[data-test-id="newsletter-success"]');
        $browser->screenshot('newsletter-success');

        // now use MailSlurp to await the email sent by our NewsletterController
        $waitForController = new MailSlurp\Apis\WaitForControllerApi(null, $config);
        $email = $waitForController->waitForLatestEmail($inbox->getId(), 60_000, true);
        assert($email->getSubject() === 'Welcome to our newsletter');

        // get email content
        $browser->resize(800, 400);
        $emailController = new MailSlurp\Apis\EmailControllerApi(null, $config);
        $previewUrls = $emailController->getEmailPreviewURLs($email->getId());
        $browser->visit($previewUrls->getPlainHtmlBodyUrl());
        $browser->screenshot('newsletter-mailable-preview');
    });
}

Run integration tests

To run the tests we first need to run the Laravel application php artisan serve in a separate terminal. Then execute API_KEY=$(API_KEY) php artisan dusk.

The test will load the application, create an email address, fill out the form, then wait for the email to arrive:

We then use the getEmailPreviewURLs method to fetch the render email and view it in our browser:

Notice how the notification is rendered using a Laravel built-in template. The Mailable on the other hand uses only our own blade view:

Conclusion

Woah! That was a lot of code but we also achieved something remarkable: we sent emails using both Mailable and Notification classes plus we tested it using Dusk integration tests and MailSlurp disposable email addresses. You can do the same and test your application end to end with real email (and SMS).

Links and more

Programmatic email in C# (test email APIs in .NET Core and ASP.NET)

MailSlurp — Fri, 01 May 2020 19:50:16 +0000

Selenium is a common integration test framework popular with C# developers. With the MailSlurp DotNet SDK you can send and receive emails from code and tests.

If you write .NET applications you probably deal with email addresses at some point: for user sign-up, email newsletters, password resets and more. If you want to test this functionality end-to-end you need test email accounts.

MailSlurp is a free API that lets you create email addresses in C# then send and receive emails with them. This article will show you how to test a web applications user sign-up using Nunit, .NET Core 2.1, Selenium and Firefox Gecko Driver.

Example application

For an example of using emails in selenium with .NET we will use a dummy web app hosted at https://playground.mailslurp.com.

This app has a real sign-up process. It lets users sign-up with an email address, then it sends them a confirmation code via email. The user can then submit the confirmation code and confirm their account. Finally the user can sign in and see a welcome screen.

We'll test this process end to end. Full source code available on GitHub.

Writing a test

To test the Playgrounds authentication process with real email addresses lets set up a .NET Core 2.1 project.

::: tip
MailSlurp's CSharp Package on NuGet supports .Net Core 2.x and 3.x. If You need another target consider the REST API.
:::

Setup

First you need Firefox and the Selenium Gecko Driver. You can install them with choco or download them manually and add them to your Path.

choco install firefox
choco install selenium-gecko-driver

Add project dependencies

Create a new .NET Core project and add the following dependencies in YourProject.csproj:

  <ItemGroup>
    <PackageReference Include="mailslurp" Version="7.1.3" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.5.0" />
    <PackageReference Include="nunit" Version="3.12.0" />
    <PackageReference Include="NUnit3TestAdapter" Version="3.16.1">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Selenium.WebDriver" Version="3.141.0" />
    <PackageReference Include="Selenium.WebDriver.GeckoDriver" Version="0.26.0.1" />
  </ItemGroup>

Create test file

Next create an Nunit test:

using System;
using System.Text.RegularExpressions;
using mailslurp.Api;
using mailslurp.Client;
using mailslurp.Model;
using NUnit.Framework;
using OpenQA.Selenium;
using OpenQA.Selenium.Firefox;

// Example usage for MailSlurp email API plugin
namespace ExampleService.Tests
{

    [TestFixture]
    public class ExampleTest
    {
        // tests will go here
    }
}

Next we need to configure Selenium. We will add a FirefoxDriver and tell it to start before our tests. Then we'll add a shutdown method after the tests have finished. Put the following inside the ExampleTest class:

private static IWebDriver _webdriver;
private static Configuration _mailslurpConfig;

// get a MailSlurp API Key free at https://app.mailslurp.com
private static readonly string YourApiKey = "your-api-key-here";

private static readonly long TimeoutMillis = 30_000L;

[SetUpFixture]
public class NunitSetup
{
    // runs once before any tests
    [OneTimeSetUp]
    public void SetUp()
    {
        // set up the webdriver for selenium
        var timeout = TimeSpan.FromMilliseconds(TimeoutMillis);
        var service = FirefoxDriverService.CreateDefaultService()
        _webdriver = new FirefoxDriver(service, new FirefoxOptions(), timeout);
        _webdriver.Manage().Timeouts().ImplicitWait = timeout;

        // configure mailslurp with API Key
        Assert.NotNull(YourApiKey);
        _mailslurpConfig = new Configuration();
        _mailslurpConfig.ApiKey.Add("x-api-key", YourApiKey);
    }

    // runs once after all tests finished
    [OneTimeTearDown]
    public void Dispose()
    {
        // close down the browser
        _webdriver.Quit();
        _webdriver.Dispose();
    }
}

Test loading the playground

Now we can write some tests. So let's load the playground app and click the sign-up button:

[Test, Order(1)]
public void CanLoadPlaygroundAppInBrowser_AndClickSignUp()
{
    // open the dummy authentication app and assert it is loaded
    _webdriver.Navigate().GoToUrl("https://playground.mailslurp.com");
    Assert.AreEqual("React App", _webdriver.Title);

    // can click the signup button
    _webdriver.FindElement(By.CssSelector("[data-test=sign-in-create-account-link]")).Click();
}

Create test email accounts

Next we need to start a user sign-up. We will need a new test email account first. Create one with MailSlurp then use it to fill the sign-up form:

private static Inbox _inbox;

[Test, Order(2)]
public void CanCreateTestEmail_AndStartSignUp()
{
    // first create a test email account
    var inboxControllerApi = new InboxControllerApi(_mailslurpConfig);
    _inbox = inboxControllerApi.CreateInbox();

    // inbox has a real email address
    var emailAddress = _inbox.EmailAddress;

    // next fill out the sign-up form with email address and a password
    _webdriver.FindElement(By.Name("email")).SendKeys(emailAddress);
    _webdriver.FindElement(By.Name("password")).SendKeys(Password);

    // submit form
    _webdriver.FindElement(By.CssSelector("[data-test=sign-up-create-account-button]")).Click();
}

If we run the test the result should look like this:

Receive confirmation email

Once the sign-up form is submitted the playground app will send a confirmation code to the email address. We can wait for the email to arrive using MailSlurp.

private static Email _email;

[Test, Order(3)]
public void CanReceiveConfirmationEmail()
{
    // now fetch the email that playground sends us
    var waitForControllerApi = new WaitForControllerApi(_mailslurpConfig);
    _email = waitForControllerApi.WaitForLatestEmail(inboxId: _inbox.Id, timeout: TimeoutMillis, unreadOnly: true);

    // verify the contents
    Assert.IsTrue(_email.Subject.Contains("Please confirm your email address"));
}

Extract content and confirm

Next let's find the verification code in the email and submit it to the confirmation screen:

private static String _confirmationCode;

[Test, Order(4)]
public void CanExtractConfirmationCode()
{
    // we need to get the confirmation code from the email
    var rx = new Regex(@".*verification code is (\d{6}).*", RegexOptions.Compiled);
    var match = rx.Match(_email.Body);
    _confirmationCode = match.Groups[1].Value;

    Assert.AreEqual(6, _confirmationCode.Length);
}

[Test, Order(5)]
public void CanConfirmUserWithEmailedCode()
{
    // fill the confirm user form with the confirmation code we got from the email
    _webdriver.FindElement(By.Name("code")).SendKeys(_confirmationCode);
    _webdriver.FindElement(By.CssSelector("[data-test=confirm-sign-up-confirm-button]")).Click();
}

Running the test should look as follows:

Sign in with confirmed user

Finally we can test that a confirmed user can sign in. Load the playground again and sign in.

[Test, Order(6)]
public void CanLoginWithConfirmedUser()
{
    // load the main page again
    _webdriver.Navigate().GoToUrl("https://playground.mailslurp.com");

    // login with email and password (we expect it to work now that we are confirmed)
    _webdriver.FindElement(By.Name("username")).SendKeys(_inbox.EmailAddress);
    _webdriver.FindElement(By.Name("password")).SendKeys(Password);
    _webdriver.FindElement(By.CssSelector("[data-test=sign-in-sign-in-button]")).Click();

    // verify that user can see authenticated content
    Assert.IsTrue(_webdriver.FindElement(By.TagName("h1")).Text.Contains("Welcome"));
}

The login should look like this:

Once logged in the user will be greeted with a welcome message.

Next steps

Selenium is a powerful testing tool. When combined with test email accounts you can test email related processes end-to-end. MailSlurp is free email API with C# bindings. Check out the documentation to get started.

Testing sign-up with real emails - Selenium Java email API tutorial (with examples)

MailSlurp — Wed, 29 Apr 2020 13:14:28 +0000

Selenium is a powerful browser testing framework. This article will show you how to use real email addresses in Selenium tests - no mail server required. These tests can be combined with automated test flows or devops pipelines to test security or application functionality end-to-end.

Many web applications rely on email: for user sign-up, password reset, newsletters, support responses and more.

This presents a challenge for QA testers using Selenium: how do we test email related processes? Well with free test email account APIs like MailSlurp we can create email addresses within tests and control them from code.

Let's see an example.

Example usage

For this example let's write a Selenium test to sign a user up to a dummy web application.

The source code for this example is available on GitHub

The test app

We'll test against playground.mailslurp.com for this example, a simple React application with a user sign-up process.

Sign up process

The playground allows a user to sign-up with an email address and password. The app then sends them the user an email containing a confirmation code. The user must copy the code and submit it to the app to confirm their account.

Once confirmed the user can access a picture of a dog by logging in!

We will test this process end to end.

Test process

We use Selenium to load the playground login form in Firefox. Then we use MailSlurp to generate an email address. Then we enter the email address into the sign up form, receive the welcome email with MailSlurp, extract the verification code and confirm the user. We'll go over each step with examples.

First let's setup the project to include Junit, Selenium, and the MailSlurp Java SDK.

Maven setup

If you use maven then create a pom.xml like so:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>java-maven-selenium</artifactId>
    <version>1.0-SNAPSHOT</version>
    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>
    <dependencies>
        <dependency>
            <groupId>com.github.mailslurp</groupId>
            <artifactId>mailslurp-client-java</artifactId>
            <version>7.0.11-RELEASE</version>
        </dependency>
        <dependency>
            <groupId>org.seleniumhq.selenium</groupId>
            <artifactId>selenium-java</artifactId>
            <version>3.4.0</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.12</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>

Gradle setup

Or if you use Gradle create a build.gradle like so:

plugins {
    id 'java'
}

group 'org.example'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

repositories {
    mavenCentral()
    // jitpack for mailslurp
    maven { url 'https://jitpack.io' }
}

dependencies {
    testCompile 'junit:junit:4.12'
    testCompile 'org.seleniumhq.selenium:selenium-java:3.4.0'

    // mailslurp client
    testCompile 'com.github.mailslurp:mailslurp-client-java:7.0.11-RELEASE'
}

Download WebDriver

Next you need to download webdriver for your platform. We prefer GeckoDriver for automating Firefox but you can use ChromeDriver with Chrome or any other if you prefer.

Configure Selenium

Now we can create a test and configure Selenium and MailSlurp. You need an API Key to use MailSlurp but it is free for personal use. Get an API Key here then create a test like this:

public class ExampleUsageTest {
    private static final String YOUR_API_KEY = "your_mailslurp_api_key_here";

    // set a timeout as fetching emails might take time
    private static final Long TIMEOUT_MILLIS = 30000L;
    private static final String WEBDRIVER_PATH = "/path/to/your/webdriver";

    private static ApiClient mailslurpClient;
    private static WebDriver driver;

    @BeforeClass
    public static void beforeAll() {
        // setup mailslurp
        mailslurpClient = com.mailslurp.client.Configuration.getDefaultApiClient();
        mailslurpClient.setApiKey(YOUR_API_KEY);
        mailslurpClient.setConnectTimeout(TIMEOUT_MILLIS.intValue());

        // setup webdriver
        System.setProperty("webdriver.gecko.driver", WEBDRIVER_PATH);
        driver = new FirefoxDriver();
        driver.manage().timeouts().implicitlyWait(TIMEOUT_MILLIS, TimeUnit.MILLISECONDS);
    }
}

The test

Now we can write some tests.

Load the application

Let's load the application and assert that the title is as we expect.

private static final String PLAYGROUND_URL = "https://playground.mailslurp.com";

@Test
public void test1_canLoadAuthenticationPlayground() {
    driver.get(PLAYGROUND_URL);
    assertEquals(driver.getTitle(), "React App");
}

To run the test run mvn install test. The result looks like this:

Start sign-up

Now let's click the sign-up button and load the sign-up page.

@Test
public void test2_canClickSignUpButton() {
    driver.findElement(By.cssSelector("[data-test=sign-in-create-account-link]")).click();
}

Create the an email address

Next we will create a new email address using the MailSlurp client.

private static Inbox inbox;

 @Test
public void test3_canCreateEmailAddressAndSignUp() throws ApiException {
    // create a real, randomized email address with MailSlurp to represent a user
    InboxControllerApi inboxControllerApi = new InboxControllerApi(mailslurpClient);
    inbox = inboxControllerApi.createInbox(null,null,null,null, null, null);

    // check the inbox was created
    assertNotNull(inbox.getId());
    assertTrue(inbox.getEmailAddress().contains("@mailslurp.com"));

    // fill the playground app's sign-up form with the MailSlurp
    // email address and a random password
    driver.findElement(By.name("email")).sendKeys(inbox.getEmailAddress());
    driver.findElement(By.name("password")).sendKeys(TEST_PASSWORD);

    // submit the form to trigger the playground's email confirmation process
    // we will need to receive the confirmation email and extract a code
    driver.findElement(By.cssSelector("[data-test=sign-up-create-account-button]")).click();
}

The result should look like this:

Receive confirmation email

Now we can use MailSlurp to receive the confirmation email that is sent by playground.

private static Email email;

@Test
public void test4_canReceiveConfirmationEmail() throws ApiException {
    // receive a verification email from playground using mailslurp
    WaitForControllerApi waitForControllerApi = new WaitForControllerApi(mailslurpClient);
    email = waitForControllerApi.waitForLatestEmail(inbox.getId(), TIMEOUT_MILLIS, UNREAD_ONLY);

    // verify the contents
    assertTrue(email.getSubject().contains("Please confirm your email address"));
}

Then we can extract the confirmation code from email body using regex pattern:

private static String confirmationCode;

@Test
public void test5_canExtractConfirmationCodeFromEmail() {
    // create a regex for matching the code we expect in the email body
    Pattern p = Pattern.compile(".*verification code is (\\d+).*");
    Matcher matcher = p.matcher(email.getBody());

    // find first occurrence and extract
    assertTrue(matcher.find());
    confirmationCode = matcher.group(1);

    assertTrue(confirmationCode.length() == 6);
}

Confirm the user and login

Now that we have the confirmation code we can submit the code to the Playground and then login with a confirmed account.
If successful we can verfiy the welcome message.

/**
 * Submit the confirmation code to the playground to confirm the user
 */
@Test
public void test6_canSubmitVerificationCodeToPlayground() {
    driver.findElement(By.name("code")).sendKeys(confirmationCode);
    driver.findElement(By.cssSelector("[data-test=confirm-sign-up-confirm-button]")).click();
}

/**
 * Test sign-in as confirmed user
 */
@Test
public void test7_canLoginWithConfirmedUser() {
    // load the main playground login page
    driver.get(PLAYGROUND_URL);

    // login with now confirmed email address
    driver.findElement(By.name("username")).sendKeys(inbox.getEmailAddress());
    driver.findElement(By.name("password")).sendKeys(TEST_PASSWORD);
    driver.findElement(By.cssSelector("[data-test=sign-in-sign-in-button]")).click();

    // verify that user can see authenticated content
    assertTrue(driver.findElement(By.tagName("h1")).getText().contains("Welcome"));
}

/**
 * After tests close selenium
 */
@AfterClass
public static void afterAll() {
    driver.close();
}

Next steps

This article showed how to test email related processes like user sign-up in Selenium with Java and MailSlurp. In this test we used them to create a new test email account with a unique email address. We then used the email address to sign-up a user and receive a confirmation code.

MailSlurp is free for personal use and has bindings for several popular languages. You can use it to create email addresses on demand then send and receive emails and attachments in code. Check it out.

Testing user sign-up for real! (Jest, Puppeteer, and test email accounts)

MailSlurp — Tue, 28 Apr 2020 14:33:03 +0000

Jest is a test framework popular in the React community and Puppeteer is a headless browser library. Together, using jest-puppeteer and MailSlurp (a FREE email API), we can write automated tests that sign up users using real email addresses in a browser.

We can then use these email addresses to receive confirmation codes and email notifications. This testing software combination is excellent for testing email dependent processes like user sign-up and email verification end-to-end.

Writing a test

In this article we will show you how to write automated tests that generate email addresses and sign-up for a dummy authentication application. We then extract the confirmation code from an a welcome email and confirm the users account.

Install

First create a NodeJs project:

npm init -y

Then install the dependencies:

npm install --save-dev jest jest-puppeteer puppeteer mailslurp-client

Configure

Next we need to setup Jest to find our tests and to use puppeteer. Edit package.json to include the following:

{
  "scripts": {
    "test": "jest"
  },
  "jest": {
    "preset": "jest-puppeteer",
    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.[jt]sx?$"
  }
}

Loading the playground

We will use the MailSlurp authentication playground to sign-up a user. We will then receive a verification email and extract the code and verify the account. The playground website looks like this:

To load this site in a Jest test let's create one:

touch sign-up.test.js

Inside the test let's add code to load the playground in a headless browser.

const assert = require('assert');
const MailSlurp = require('mailslurp-client').default;
const mailslurp = new MailSlurp({ apiKey: process.env.API_KEY });

describe('sign-up process', () => {

  it('can load oauth demo site', async () => {
    await page.goto('https://playground.mailslurp.com')
    await expect(page).toMatch('Sign in to your account')
  })

If we now run this test we will see the following result:

$ API_KEY=your-api-key npm t

PASS  ./sign-up.test.js (1.165s)
  sign-up process
  ✓ can load oauth demo site (567ms)

Testing the sign-up process

Now that we know how to write tests let's use MailSlurp to sign-up with a new email address. We can generate test email accounts on demand with MailSlurp and use them to test email processes.

it("can click sign up link", async () => {
  await expect(page).toClick('[data-test="sign-in-create-account-link"]');
  await expect(page).toMatch("Testable Sign Up Form");
});

const password = "test-password";
let inbox;
let code;

it("can sign-up with a new email address", async () => {
  // IMPORTANT: create a new email address for the test run
  inbox = await mailslurp.createInbox();

  // fill out the new user form with generating email address
  await expect(page).toFillForm('[data-test="sign-up-body-section"]', {
    email: inbox.emailAddress,
    password: password
  });

  // submit the new user form (which will send a confirmation email)
  await expect(page).toClick('[data-test="sign-up-create-account-button"]');
});

Receiving the welcome email

Once we have signed up a user we should then receive the confirmation email inside the test using MailSlurp and extract the confirmation code:

it("can fetch confirmation code", async () => {
  // fetch the email from mailslurp
  const email = await mailslurp.waitForLatestEmail(inbox.id);

  // verify that it contains the code
  assert.strictEqual(/verification code is/.test(email.body), true);

  // extract the confirmation code
  code = /([0-9]{6})$/.exec(email.body)[1];
});

Confirming the account

Now that we have received the email address in code we can use Jest and Puppeteer to fill out the confirmation form and submit the confirmation code.

it("can enter confirmation code and confirm user", async () => {
  await expect(page).toFillForm('[data-test="confirm-sign-up-body-section"]', {
    code: code
  });
  await expect(page).toClick('[data-test="confirm-sign-up-confirm-button"]');
});

Test user login

Now that our account is confirmed we can login with the email address we generated and the test password. The end result should show a welcome screen

  it('can log in with confirmed account', async () => {
    await expect(page).toMatch('Sign in to your account')
    // fill out username (email) and password
    await expect(page).toFillForm('#root', {
      username: inbox.emailAddress,
      password: password
    })
    // submit
    await expect(page).toClick('[data-test="sign-in-sign-in-button"]')
  });

  it('shows the successful greeting', async () => {
    await page.waitForFunction('document.body.innerText.includes("Welcome")');
    await expect(page).toMatchElement('h1', { text: 'Welcome' })
  })
})

A screenshot of the welcome screen shown after successful logins:

Running the example

Now when we execute our tests we can see a full sign-up, confirmation, and login flow being tested with real email addresses.

PASS  ./sign-up.test.js (9.165s)
    sign-up process
    ✓ can load oauth demo site (567ms)
    ✓ can click sign up link (18ms)
    ✓ can sign-up with a new email address (1733ms)
    ✓ can fetch confirmation code (2868ms)
    ✓ can enter confirmation code and confirm user (104ms)
    ✓ can log in with confirmed account (690ms)
    ✓ shows the successful greeting (2948ms)

We hope this example helps. For more information please see:

Low-code HTML forms that submit directly to your email address! (Free serverless forms)

MailSlurp — Tue, 21 Apr 2020 13:05:07 +0000

I built a free API that you can submit HTML forms to and receive the data to your email - attachments included!

Check it out

Why did I make it?

I wanted an easy way to make contact forms for static websites. With MailSlurp forms you can now create forms that submit to your email address without any server or Javascript.

Example

Just POST any HTML form to https://api.mailslurp.com/forms?_to=YOUR_EMAIL_ADDRESS.

<form action="https://api.mailslurp.com/forms?_to=YOUR_EMAIL" method="post">
  <!-- include any form fields, even files -->
  <textarea name="example"></textarea>
</form>

Any named input field will be put into a table and sent to your email address within seconds.

Attachments

You can add files too by adding an enctype="multipart/form-data" attribute to your <form> element.

<form
  action="https://api.mailslurp.com/forms"
  method="post"
  enctype="multipart/form-data">

  <input multiple name="files" type="file">
  <button type="submit">Send to me</button>

</form>

More settings

You can set the subject, bcc, cc of the email and more by adding query parameters to the url. You can see a full list of config options here.

You can also alias or mask your email address behind an MailSlurp ID so that your email address is not exposed to the public.

<form action="https://api.mailslurp.com/forms" method="post">
  <!-- hide email with an alias (create a free account for this) -->
  <input
    type="hidden"
    name="_toAlias"
    value="9b32cb34-e75a-48a6-8f6c-817204c354e7"
  />
  <!-- data to submit -->
  ...
</form>

Get started

MailSlurp forms are free :). If you want extra features like on demand email addresses, or a MailServer API then you can explore MailSlurp's paid account. Have fun!

Test user sign-up with real emails using NodeJS and WebDriver (wdio)

MailSlurp — Tue, 21 Apr 2020 09:26:21 +0000

Test user sign-up and password reset using NodeJS and WebDriver (wdio)

This example demonstrates use of MailSlurp with NodeJS, Webdriver.io (WDIO), Selenium and Chrome to test user processes that depend on email. It tests user sign-up and email confirmation using the MailSlurp OAuth2 Playground as a dummy login application (shown below).

About

Each test run does the following:

generates a real, randomized email address using MailSlurp
signs up with it in the browser
captures the email confirmation code with MailSlurp
enters in the confirmation code in the browser.

MailSlurp is free for personal use so sign up to run the example yourself.

Installing WebDriver and WDIO

In order to test a websites login process you need to load the website into a browser and performs some actions against it. We will use WDIO for this example: a Javascript library that automates browsers.

To install create a package.json file and paste the following:

{
  "scripts": {
    "test": "wdio wdio.conf.js"
  },
  "dependencies": {
    "@wdio/cli": "^5.13.2",
    "@wdio/local-runner": "^5.13.2",
    "@wdio/mocha-framework": "^5.13.2",
    "@wdio/selenium-standalone-service": "^5.13.2",
    "@wdio/spec-reporter": "^5.13.2",
    "chromedriver": "^76.0.0",
    "mailslurp-client": "^6.5.0",
    "wdio-chromedriver-service": "^5.0.2"
  }
}

Then run npm install

Configuring WDIO

Now add a wdio.conf.js file so we can configure WDIO to load the MailSlurp playground in the browser.

const config = {
  runner: "local",
  path: "/",
  specs: ["test/*.test.js"],
  exclude: [],
  maxInstances: 10,
  capabilities: [
    {
      maxInstances: 5,
      browserName: "chrome"
    }
  ],
  logLevel: "info",
  bail: 0,
  baseUrl: "https://playground.mailslurp.com",
  waitforTimeout: 30000,
  connectionRetryTimeout: 90000,
  connectionRetryCount: 3,
  framework: "mocha",
  services: ["chromedriver"],
  reporters: ["spec"],
  mochaOpts: {
    ui: "bdd",
    timeout: 60000
  }
};

exports.config = config;

Write a test to sign up user

Configure MailSlurp

Create a test file called sign-up.test.js. Now let's configure MailSlurp:

const assert = require("assert");
const MailSlurp = require("mailslurp-client").default;
const apiKey = "your-api-key";
const mailslurp = new MailSlurp({ apiKey });

Try loading the Playground

Our first test should load the playground and assert the sign-up form is present.

describe("sign up process", () => {
  it("can load playground app", async () => {
    await browser.url("/");
    await browser.setWindowSize(1200, 1200);
  });
});

If we run the test with npm run test we should see passing tests.

The first page to load is the login screen. As we want to sign-up let's click the link for that page in our test.

it("can load the sign-up section", async () => {
  // find the create account link and click it
  await $('[data-test="sign-in-create-account-link"]').then(e => e.click());
  await $('[data-test="sign-up-header-section"]')
    .then(e => e.getText())
    .then(text => assert.strictEqual(text, "Testable Sign Up Form"));
});

Create random email address and sign up

Now for the important part: creating a real email address on demand to sign-up a user with.

let inbox;
it("can sign-up with new user", async () => {
  // create a new email address for the test run
  inbox = await mailslurp.createInbox();

  // fill out and submit the new user form
  await $('[name="email"]').then(e => e.setValue(inbox.emailAddress));
  await $('[name="password"]').then(e => e.setValue(password));
  await $('[data-test="sign-up-create-account-button"]').then(e => e.click());
});

Notice how we created a new email address in each test run:

inbox = await mailslurp.createInbox();

The inbox response object contains data like so:

{
  id: 'abc123',
  emailAddress: 'abc123@mailslurp.com'
}

The email address created is real and can receive emails sent from any application (including our login Playground).

Fetch confirmation email and verify account

Once the sign-up form has been submitted we can use MailSlurp to fetch the confirmation code and confirm the users account in the browser.

it("can fetch confirmation code", async () => {
  // fetch the email from mailslurp
  const email = await mailslurp.waitForLatestEmail(inbox.id);

  // verify that it contains the code
  assert.strictEqual(/verification code is/.test(email.body), true);

  // extract the confirmation code
  code = /([0-9]{6})$/.exec(email.body)[1];
});

it("can enter confirmation code and confirm user", async () => {
  await $('[name="code"]').then(e => e.setValue(code));
  await $('[data-test="confirm-sign-up-confirm-button"]').then(e => e.click());
});

Notice the waitForLatestEmail call to MailSlurp:

const email = await mailslurp.waitForLatestEmail(inbox.id);

This call fetches the latest email in the given inbox or holds the connection open until the first email is received. This means the method will return the confirmation email sent by the Playground.

Can login with confirmed user

With our email address now confirmed lets log into the Playground and confirm we have access. A successful login should show a picture of a dog like so:

it("can log in with confirmed account", async () => {
  // assert we see the sign in form
  await $('[data-test="sign-in-header-section"]')
    .then(e => e.getText())
    .then(text => assert.strictEqual(text, "Sign in to your account"));

  // fill out username (email) and password
  await $('[name="username"]').then(e => e.setValue(inbox.emailAddress));
  await $('[name="password"]').then(e => e.setValue(password));

  // submit
  await $('[data-test="sign-in-sign-in-button"]').then(e => e.click());
});

it("shows the successful greeting", async () => {
  await $('[data-test="greetings-nav-bar"]')
    .then(e => e.getText())
    .then(text => assert.strictEqual(/Hello/.test(text), true));
});

Conclusion

MailSlurp lets you send and receive emails from randomly assigned email addresses. It's great for testing authentication flows with Webdriver, Cypress, Jest and more. It's free for personal use so sign up today!

Test email sign-up with real email addresses (NodeJS, CypressJS, and MailSlurp)

MailSlurp — Tue, 14 Apr 2020 12:59:40 +0000

Test emails with Cypress JS

Javascript

Cypress is an amazing end-to-end testing framework. It's popular, bundles it's own chrome browser and is easily extended.

Cypress let's you test many parts of a website or web application with a browser in an automated way. It's like Selenium but a lot more user friendly.

Testing with real email addresses

Many application use emails for account login and creation. Testing logins with Cypress is easy if you have a designated test user. But what about sign ups?

Email sign up has to be the most important aspect of any application and without access to unique, private email addresses end-to-end testing is difficult.

Luckily there's MailSlurp, a free API that let's you create real, randomized email addresses on demand. It also let's you send and receive email programmatically - perfect for end-to-end testing user sign-up flows!

An example

To demonstrate let's imagine you worked at Twitter (😎) and you wanted to test the user sign up process end to end.

Setup Cypress

To setup make sure you have NodeJS installed then run:

npm install --save cypress

Next create a test spec in with the following folder structure:

cypress
└── integration
    └── example.spec.js

Inside integration/example.spec.js let's write our first test:

Writing a test

Let's start simple and write a test that loads the Twitter sign up screen with Cypress.

That would look a little like this:

describe("Sign up", () => {
  context("Example sign up page", () => {
    it("can load the sign up form", () => {
      cy.visit("https://twitter.com/i/flow/signup");
      cy.contains("Create your account");
    });
  });
});

When we run npx cypress run Cypress loads the Twitter sign up form and asserts thast Create your account is displayed on the page. The output looks like this:

Testing with emails in Cypress

Now let's integrate email address into our test using MailSlurp. MailSlurp requires an api key but it's free for personal use so sign up to get one.

Once you've sign up we can extend Cypress with a command to creates new email address when we need them.

Generate test email accounts in Cypress

To extend Cypress first create a support folder in the cypress directory and place an index.js and a command.js inside it. Like so:

cypress
├── integration
│   └── example.spec.js
└── support
    ├── commands.js
    └── index.js

Inside index.js import the commands.

import './commands'

Now let's set up a command called newEmailAddress inside commands.js that calls MailSlurp and creates an email address on demand.

const { MailSlurp } = require("mailslurp-client");

Cypress.Commands.add("newEmailAddress", () => {
  // instantiate MailSlurp
  const mailslurp = new MailSlurp({ apiKey: Cypress.env("API_KEY") });
  // return { id, emailAddress } or a new randomly generated inbox
  return mailslurp.createInbox();
});

Using our `newEmailAddress` command

Now that we have a Cypress command that returns a new email address we can put it all together in our sign up test.

describe("Sign up", () => {
  context("Example sign up page", () => {
    it("can generate a new email address to test sign up", () => {
      // get an email address for this test run
      cy.newEmailAddress().then(({ emailAddress }) => {
        // load the twitte rform
        cy.visit("https://twitter.com/i/flow/signup");
        // click to enter email addres
        cy.contains("email instead").click();
        cy.get("input[type=email]").type(emailAddress);
        // assert that email address was entered
        cy.get("input[type=email]").should("contain.value", "@mailslurp.com");
        // submit the form, get the verification code, verify the user (see docs for those examples)
      });
    });
  });
});

Notice that we destructure the returned value from our helper command.

cy.newEmailAddress().then(({ emailAddress }) => {
  /* do stuff */
});

Results

Now we can run our tests again and pass in a MailSlurp api key.

npx CYPRESS_API_KEY=your-api-key cypress run

Cypress loads our login screen and enters a real address that was generated with MailSlurp.

Next Steps

The next steps would be to submit the form, fetch the verification code sent to the email address using MailSlurp and verify the account.

That's right MailSlurp let's you receive email verification codes inside tests so you can sign up and verify the users end-to-end.

This means truly testing your app's most important processes like user sign up and email verification.

For more information on receiving emails in tests see the developers sections.

Code Samples

As always you can find this and other examples in the MailSlurp examples repository. Use MailSlurp free and take your end-to-end test coverage to 💯 !

How to send emails in Javascript (3 ways with Node examples)

MailSlurp — Tue, 14 Apr 2020 12:53:28 +0000

How to send emails in Javascript (3 ways to send and test emails with NodeJS)

About

Sending emails is a core requirement of many modern businesses. Whether it's invoice receipts, password resets, or support messages many applications send emails programmatically in response to different events. Sending emails these days is easy and doesn't require knowledge of SMTP, POP3, or IMAP! Here are three ways to send email in NodeJS and how to test them.

Transactional mail services

There are many email-as-a-service APIs. Some of the most popular names include SendGrid, MailJet, MailGun. They each offer different features and pricing models but they all send emails on demand via API request.

Usually setup is required with the service to enable sending from a custom domain. Once this is done emails are typically sent with an SDK and REST API request. For this example we'll demonstrate sending emails with the SendGrid SDK and Node.

Installing SendGrid SDK

You can get the official SendGrid Javascript library from NPM.

npm install -s @sendgrid/mail

Sending an eail with SendGrid

Sending an email is easy. Just provide your API key and then describe the message you wish to send. Lastly call send and let SendGrid handle the rest.

// get a instance of sendgrid and set the API key
const sendgrid = require("@sendgrid/mail");
sendgrid.setApiKey(SENDGRID_API_KEY);

// construct an email
const email = {
  to: "test@mailslurp.com",
  from: "test@mailslurp.com",
  subject: "My first email",
  text: "Hello world"
};

// send the email via sendgrid
sendgrid.send(email);

SendGrid also supports an html property for sending HTML formatted emails. It also has a feature-rich templating system with a browser based UI designer. Pricing is reasonable but for more control try the next option: AWS SES.

Email as infrastructure

If you run your application on cloud infrastructure chances are your cloud provider will have an email sending service. Amazon AWS has a Simple Email Service called SES. It's a great option for those who want a bit more control. You can define email domains and routing rules with Terraform so that email becomes a managed part of your infrastructure.

Setup AWS SES with Terraform

SES requires a bit of setup but once enabled can be easily used with NodeJS. All AWS infrastructure can be enable by hand in the console but a better way to manage cloud resources is with Terraform.

Here is how to set up an SES domain with Terraform. This will allow us to send emails from a specific address.

resource "aws_ses_domain_identity" "example" {
  domain = "yourdomain.com"
}

resource "aws_route53_record" "example_amazonses_verification_record" {
  zone_id = "your_zone_id"
  name    = "_amazonses.yourdomain.com"
  type    = "TXT"
  ttl     = "600"
  records = ["${aws_ses_domain_identity.example.verification_token}"]
}

Sending email with AWS SES and Node

So, now that SES is set up we can call it from Node. First we need the AWS SDK.

npm install -s aws-sdk

Now let's create a script to send the email.

// configure the AWS sdk
const AWS = require("aws-sdk");
AWS.config.update({ region: "us-west-2" });

// Create email params
const params = {
  Destination: {
    ToAddresses: ["my-test-email@gmail.com"]
  },
  Message: {
    Body: {
      Text: {
        Charset: "UTF-8",
        Data: "Hello world!"
      }
    },
    Subject: {
      Charset: "UTF-8",
      Data: "My email subject"
    }
  },
  Source: "no-reply@yourdomain.com"
};

// Create the promise and SES service object
const sendPromise = new AWS.SES({ apiVersion: "2010-12-01" })
  .sendEmail(params)
  .promise();

// Handle promise's fulfilled/rejected states
sendPromise
  .then(data => {
    console.log(data.MessageId);
  })
  .catch(err => {
    console.error(err, err.stack);
  });

Custom SMTP server

While transactional mail services and SES are pretty straight forward if you need ultimate control deploying your own SMTP server is the way to go.

You can deploy an SMTP server on Kubernetes with a bit of setup and configuring. I won't go into that here as it is a rather big job. Note SMTP solutions are only suggested if you have some unusual email sending requirements.

Sending email via SMTP in Node

Once that's done you can easily interact with your SMTP server using the NPM package nodemailer.

npm install -s nodemailer

And here's an example of sending an email with nodemailer.

const nodemailer = require("nodemailer");

const transporter = nodemailer.createTransport({
  host: "smtp.yourdomain.email",
  port: 587,
  secure: false,
  auth: {
    user: SMTP_USER
    pass: SMTP_PASSWORD
  }
});

// send mail with defined transport object
transporter.sendMail({
  from: '"YourCompany" <no-reply@yourdomain.com>',
  to: "customer@example.com",
  subject: "Test email",
  text: "Hello world"
});

Testing email sending

So we've just seen three different ways to send emails with Node. But how do we test it? We could test our scripts manually and use our own email addresses as te recipient but this process is slow and unreliable. Ideally we want to test email sending automatically as part of an end-to-end or smoke test.

With MailSlurp you can create new email inboxes on the fly, send emails to them using your service, and then verify the results - all from within a test suite.

Install MailSlurp SDK

First you want to sign up for MailSlurp - it's free to start. Then let's install the MailSlurp SDK and the Jest test framework (you can use any framework you like).

npm install -s jest mailslurp-client

Testing emails with Jest

Let's write a simple test that:

creates a new email address with MailSlurp
invokes our service's email sending function
sends an email to our MailSlurp address
calls MailSlurp to get this email
verifies the results

Using the SendGrid example as a base our test might look something like this:

// can your app handle inbound emails
import { MailSlurp } from "mailslurp-client";
const api = new MailSlurp({ apiKey: "test" });

test("my app can send emails", async () => {
  // create a new email address for this test
  const inbox = await api.createInbox();

  // trigger an app action that sends an email
  await signUpForMyApp(inbox.emailAddress);

  // fetch sent email from the inbox
  // include a retryTimeout and minCount so that
  // MailSlurp waits for an email
  const emails = await api.getEmails(inbox.id, {
    minCount: 1,
    retryTimeout: 60000
  });

  // assert that the correct email was sent
  expect(emails[0].length).toBe(1);
  expect(emails[0].content).toBe("Hello world");
});

That's it! Now you can test your email sending functions with real email addresses so you know for sure that your emails are working.

Summary

Sending emails is easy these days. There are tons of services available each with different features, pricing and control. For a quickstart try SendGrid, MailJet or MailGun. For more control try Amazon SES. For even further control try running an SMTP server and use Nodemailer.

With every emailing solution it's important to test that messages are really sent and received. Many email providers apply spam filters so the only way to know for sure that your emails are working is with an end-to-end test using real addresses. Luckily, MailSlurp has you covered. Check it out!

Deploy Redash to AWS with Terraform

MailSlurp — Thu, 31 Oct 2019 00:00:00 +0000

Deploy Redash to AWS with Terraform (Self-hosted analytics and graphing for your database)

Redash is a popular open-source graphing dashboard that can be used to monitor sales, databases, data and more. In this post we will deploy it to AWS using an EC2 instance and Terraform. At MailSlurp we use Redash to monitor the flow of emails in and out of our servers. You can use MailSlurp to create unlimited test email accounts then send and receive email from code or tests!

What is Redash?

Redash is an open-source data visualization tool used by companies as diverse as Soundcloud, Mozilla, and Waze. It allows developers and analyts to query data, graph results, and share insights with others. The best thing about Redash is that it is completely free to self-host (minus your own infrastructure costs).

Why deploy self-hosted Redash?

Redash.io offers a super simple one-click start for hmanaged Redash instances. These are great for companies that want data insights fast but for companies with smaller budgets or developers who want extra control over data and security self-hosting Redash is a valuable endeavour.

What is terraform?

Terraform is an "infrastructure-as-code" framework that lets you create servers, load-balancers, databases and more in a number of cloud providers using a special HCL syntax.

You define resources in Terraform code then apply the code and Terraform will compare the current state of your cloud resources with the code you have written. If something is new or missing it will be created in the cloud for you.

How does Redash work?

Redash is not a trivial application (hence the hosted solutions). It has several databases, worker threads, and a web interface. Setting all that up could be difficult. Fortunately, Redash.io provides a set of prebuilt and self-contained images for a number of platforms including AWS.

Redash on AWS

The recommended way to deploy Redash on an AWS account is to use a region-appropriate AMI image (listed here) and an EC2 instance. This can be done manually using the AWS console but a more maintainable approach would be to use Terraform.

What is Terraform?

Terraform is a declarative infrastructure system that let’s you define your cloud stacks in a text-based versionable way. If you haven’t used it before take a look at the [getting started guide] first.

Deploying with Terraform

Spinning up an EC2 machine with a Redash AMI is really straight forward withe Terraform. Assuming you have already set up a Terraform project with an AWS provider resource we can use Terraform to define an EC2 instance and security group required for redash. Here is what that looks like:

locals {
  # Redash recommend AMI for us-west-2
  # https://redash.io/help/open-source/setup#aws
  ami = "ami-0c457f229774da543"
  instance_type = "t2.small"
}

# security group to allow ingress/egress
resource "aws_security_group" "redash" {
  name = "redash_sg"

  ingress {
    from_port = 22
    to_port = 22
    protocol = "TCP"
    cidr_blocks = ["0.0.0.0/0"]
  }

  ingress {
    from_port = 80
    to_port = 80
    protocol = "TCP"
    cidr_blocks = ["0.0.0.0/0"]
  }

  ingress {
    from_port = 443
    to_port = 443
    protocol = "TCP"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    from_port = 0
    to_port = 0
    protocol = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# ec2 instance running redash image
resource "aws_instance" "redash" {
  ami = local.ami
  instance_type = local.instance_type
  security_groups = [aws_security_group.redash.name]

  tags = {
    Name = "Redash"
  }
}

Notice the AMI used is specific for my region: us-west-2. Alter the AMI to suit your region requirements.

Applying Terraform changes

To apply your Terraform file run

terraform init
terraform apply --auto-approve

The output should indicate the creation of a new EC2 instance using the Redash AMI.

Connecting to your Redash instance

Once the EC2 machine has started you can connect to the public DNS address listed in the AWS EC2 console. If everything worked you should now be greeted with a setup screen. Create your admin account to continue.

Voila

You are now ready to connect datasources and begin visualizing your data. See the Redash open source setup for more configuration options.

Why though?

MailSlurp uses Redash as an alternative to Grafana to graph user metrics and prioritise product features. MailSlurp is a free email testing API that let’s you create real email addresses on demand. You can send and receive email via HTTP, SDK, or a hosted web dashboard. Check it out!

Do you really need MailChimp? (transactional emails with AWS SES, Terraform and Lambda)

MailSlurp — Fri, 22 Feb 2019 00:00:00 +0000

Do you really need MailChimp? (transactional emails with AWS SES, Terraform and Lambda)

What are transactional emails?

Many applications need to send emails. Usually these emails are triggered in code in response to a given event, such as a product purchase. For this reason they are often called Transactional Emails. But an app or backend service can’t just send an email, it needs to have a SMTP server setup. Setting up email servers can be tricky, so a number of services exist for sending emails with API requests. The main players are: MailChimp (Mandrill), Sendgrid, MailGun, and SendinBlue.

Recently however more developers have been using Amazon’s “simple email service” or SES. It’s not as famous as the others but is developer focused and fits nicely into any existing AWS infrastructure. Plus, a lot of the time SES is easier and cheaper to use. Here is a simple guide for setting up an SES domain, sending emails, and receiving emails. Later, we’ll go over testing your email actions with real email addresses.

If you'd like to use a powerful alternative built on SES try MailSlurp.

Building the infrastructure in AWS

Registering a domain

First off, you need a domain to send and receive email from. If you already have one that’s great, if not go ahead and get one. You also need an AWS account.

Adding Route53 domain records

Next we need to add MX records for this domain to Route53. I’m going to use Terraform to set up my AWS infrastructure because it is a lot more maintainable in the long run.

First let’s create some variables in Terraform:

variable "zone_id" {
  default = "your-route-53-domain-zone-id"
}

variable "domain" {
  default = "your-domain-here"
}

Now let’s create an SES domain identity and the Route53 records associated with it. This will let us send emails from the domain.

# ses domain
resource "aws_ses_domain_identity" "ms" {
  domain = "${var.domain}"
}

resource "aws_route53_record" "ms-domain-identity-records" {
  zone_id = "${var.zone_id}"
  name = "_amazonses.mailslurp.com"
  type = "TXT"
  ttl = "600"

  records = [
    "${aws_ses_domain_identity.ms.verification_token}",
  ]
}

# ses dkim
resource "aws_ses_domain_dkim" "ms" {
  domain = "${aws_ses_domain_identity.ms.domain}"
}

resource "aws_route53_record" "ms-dkim-records" {
  count = 3
  zone_id = "${var.zone_id}"
  name = "${element(aws_ses_domain_dkim.ms.dkim_tokens, count.index)}._domainkey.mailslurp.com"
  type = "CNAME"
  ttl = "600"

  records = [
    "${element(aws_ses_domain_dkim.ms.dkim_tokens, count.index)}.dkim.amazonses.com",
  ]
}

# ses mail to records
resource "aws_route53_record" "ms-mx-records" {
  zone_id = "${var.zone_id}"
  name = "${var.domain}"
  type = "MX"
  ttl = "600"

  records = [
    "10 inbound-smtp.us-west-2.amazonses.com",
    "10 inbound-smtp.us-west-2.amazonaws.com",
  ]
}

resource "aws_route53_record" "ms-spf-records" {
  zone_id = "${var.zone_id}"
  name = "${var.domain}"
  type = "TXT"
  ttl = "600"

  records = [
    "v=spf1 include:amazonses.com -all",
  ]
}

Setting up SES receipt rules

Great, now we can send and receive from the domain we registered. But we still need to tell SES to use this domain with a set of email addresses. These configurations are called receipt rule sets. Let’s create a rule that catches all inbound emails to any address in our domain and saves them to S3 and notifies an SNS topic.

# ses rule set
resource "aws_ses_receipt_rule_set" "ms" {
  rule_set_name = "ms_receive_all"
}

resource "aws_ses_active_receipt_rule_set" "ms" {
  rule_set_name = "${aws_ses_receipt_rule_set.ms.rule_set_name}"

  depends_on = [
    "aws_ses_receipt_rule.ms",
  ]
}

# lambda catch all
resource "aws_ses_receipt_rule" "ms" {
  name = "ms"
  rule_set_name = "${aws_ses_receipt_rule_set.ms.rule_set_name}"

  recipients = [
    "${var.domain}",
  ]

  enabled = true
  scan_enabled = true

  s3_action {
    bucket_name = "${aws_s3_bucket.ms.bucket}"
    topic_arn = "${aws_sns_topic.ms2.arn}"
    position = 1
  }

  stop_action {
    scope = "RuleSet"
    position = 2
  }

  depends_on = ["aws_s3_bucket.ms", "aws_s3_bucket_policy.ms_ses", "aws_lambda_permission.with_ses"]
}

We might also want to catch email errors. Let’s add a rule for that and send them to a cloudwatch log.

resource "aws_ses_configuration_set" "ms" {
  name = "ms-ses-configuration-set"
}

resource "aws_ses_event_destination" "ses_errors" {
  name = "ses-error-sns-destination"
  configuration_set_name = "${aws_ses_configuration_set.ms.name}"
  enabled = true

  matching_types = [
    "reject",
    "reject",
    "send",
  ]

  sns_destination {
    topic_arn = "${aws_sns_topic.ms2_ses_error.arn}"
  }
}

resource "aws_ses_event_destination" "ses_cloudwatch" {
  name = "event-destination-cloudwatch"
  configuration_set_name = "${aws_ses_configuration_set.ms.name}"
  enabled = true

  matching_types = [
    "reject",
    "reject",
    "send",
  ]

  cloudwatch_destination = {
    default_value = "default"
    dimension_name = "dimension"
    value_source = "emailHeader"
  }
}

How SNS fits in

So in the above rulesets we defined a catch all for all inbound email. It’s actions were to save the email to S3 and then notify an SNS topic. SNS is a simple notification service that we can subscribe to within our application or with a lambda to handle inbound emails. The event we receive in these handlers will contain a link to the S3 bucket item containing the email. Here is how we can set up an SNS topic in Terraform with a lambda to handle the event.

resource "aws_sns_topic" "ms2" {
  name = "ms2-receipt-sns"
}

resource "aws_sns_topic_subscription" "ms2_receive" {
  topic_arn = "${aws_sns_topic.ms2.arn}"
  protocol = "lambda"
  endpoint = "${aws_lambda_function.ms_receive_mail.arn}"
}

resource "aws_sns_topic" "ms2_ses_error" {
  name = "ms2-ses-error"
}

Create a Lambda to handle your emails

You could at this point do anything you like with the SNS topic to handle emails. You could subscribe to it within your application, or you could hook it up to a Lambda. I’ll show you how you might right a Lambda for this kind of event and act on inbound emails.

Here’s what a Lambda might look like:

import os
from botocore.vendored import requests

# handle the event here
# (the object will contain a url to the S3 item containing the full email)
def handler(event, context):
    print(event)

And here is how we can deploy the Lambda using Terraform.

# this points to your lambda python script and zips it during terrafom apply
data "archive_file" "ms_receive_mail" {
  type = "zip"
  source_file = "${path.module}/${var.receive_dist}"
  output_path = "${path.module}/dist/receive.zip"
}

# receive mail lambda definition uses the data archive file
resource "aws_lambda_function" "ms_receive_mail" {
  role = "${aws_iam_role.lambda.arn}"
  handler = "lambda.handler"
  runtime = "python3.6"
  filename = "${data.archive_file.ms_receive_mail.output_path}"
  function_name = "ms_receive_mail"
  source_code_hash = "${base64sha256(file(data.archive_file.ms_receive_mail.output_path))}"
  timeout = "${var.receive_lambda_timeout}"
}

# allow sns to invoke the lambda
resource "aws_lambda_permission" "sns_notify_ms_receive" {
  statement_id = "AllowExecutionFromSNS"
  action = "lambda:InvokeFunction"
  function_name = "${aws_lambda_function.ms_receive_mail.function_name}"
  principal = "sns.amazonaws.com"
  source_arn = "${aws_sns_topic.ms2.arn}"
}

Using SES

Recieving an email

We now have Route53, SES, SNS and a Lambda in place to handle inbound emails. We can now send an email from some email client to “test@mydomain.com” and watch our Lambda get invoked. From this point it’s up to you how you want to handle inbound email events.

Sending a transactional email

Now to the crux of the article: sending transactional emails. With the setup we created above we can now send emails from any address on our registered domain with a simple API call to AWS. For this, the best approach is to use the AWS SDK in your given language. I use a lot of Kotlin for MailSlurp so I’ll show you my approach using the AWS SES SDK for Java.

// gradle dependencies
dependencies {
        compile "com.amazonaws:aws-java-sdk-ses:${awsVersion}"
}


// lets create a client for sending and receiving emails with SES
@Service
class SESClient {

    @Autowired
    lateinit var appConfig: AppConfig

    lateinit var client: AmazonSimpleEmailService

    @PostConstruct
    fun setup() {
        client = AmazonSimpleEmailServiceClientBuilder.standard().withRegion(appConfig.region).build()
    }
}

And here is how you would send an email with the given client.

@Service
class SESService : MailService {

    @Autowired
    private lateinit var appConfig: AppConfig

    @Autowired
    private lateinit var sesClient: SESClient

    override fun sendEmail(emailOptions: SendEmailOptions) {
        // validate options
        if (emailOptions.to.isEmpty()) {
            throw Error400("No `to address` found for send")
        }
        // build message
        val content = Content().withCharset(emailOptions.charset).withData(emailOptions.body)
        val body = if (emailOptions.isHTML) {
            Body().withHtml(content)
        }
        else {
            Body().withText(content)
        }
        val message = Message()
                .withBody(body)
                .withSubject(Content().withCharset(emailOptions.charset).withData(emailOptions.subject))
        val request = SendEmailRequest()
                .withDestination(Destination()
                        .withToAddresses(emailOptions.to)
                        .withBccAddresses(emailOptions.bcc)
                        .withCcAddresses(emailOptions.cc))
                .withMessage(message)
                .withReplyToAddresses(emailOptions.replyTo.orElse(appConfig.defaultReplyTo))
                .withSource(emailOptions.from.orElseThrow { Error400("Missing `from address` for email send") })

        // send
        sesClient.client.sendEmail(request)
    }
}

Pros and cons of AWS SES

SES is great but there are some downsides:

There is no GUI for non-coders to send and receive emails
There is no transactional email contact management
Lacking many features that make other providers great

Positives include:

Cheaper than other providers
More control
Fits with existing infrastructure

Testing your transactional emails

So all this infrastructure wouldn’t be much use if we we’re sure of it’s reliability. That’s why end-to-end testing email functionality is so important. We can test whether our infra receives and handles real emails using MailSlurp!

How does email testing work?

Basically, MailSlurp is an API that let’s you create new email addresses for use with testing. You can create as many as you want and send and receive emails from them via an API or SDKs.

Writing a test for inbound emails

First you need to sign up for MailSlurp and obtain a free API Key. Then let’s use one of the SDKs to test our domain.

We can install the SDK for javascript using npm install mailslurp-client. Then in a test framework like Jest or Mocha we can write:

// javascript jest example. other SDKs and REST APIs available
import * as MailSlurp from "mailslurp-client";
const api = new MailSlurp({ apiKey: "your-api-key" });

test("my app can receive and handle emails", async () => {
  // create a new email address for this test
  const inbox = await api.createInbox();

  // send an email from the new random address to your application
  // the email will by sent from something like '123abc@mailslurp.com`
  await api.sendEmail(inbox.id, { to: "contact@mydomain.com" });

  // assert that app has handled the email in the way that we chose
  // this function would be written by you and validate some action your lambda took
  expect(myAppReceivedEmail()).resolves.toBe(true);
});

If we run this test and it passes, that means that all our infrastructure is working and our Lambda is correctly handling our events.

We just tested our inbound email handling code with a real email address and real emails.

Testing transactional emails (are they actually sent?)

Lastly let’s test whether our app can actually send emails and whether they are properly received. We could do this by sending an email to our own personal account each time and manually confirming its existance but that won’t fit well into an automated CD test suite. With MailSlurp we can test the receiving or real transactional emails with real addresses during automated testing. This ensures that key parts of our application (emails) are actually working.

What does it look like?

// can your app send emails properly
import * as MailSlurp from "mailslurp-client"
const api = new MailSlurp({ apiKey: "your-api-key" })

test('my app can send emails', async () => {
    // create a new email address for this test
    const inbox = await api.createInbox()

    // trigger an app action that sends an email
    // to the new email address. this might be a new sign-up
    // welcome email, or a new product payment for example
    await signUpForMyApp(inbox.emailAddress)

    // fetch welcome email from the inbox we created
    const emails = await api.getEmails(inbox.id, { minCount: 1 })

    // assert that the correct email was sent
    expect(emails[0].length).toBe(1)
    expect(emails[0].content).toBe(expectedContent)

    // profit!
}

Now if this test passes we can rest assured that our application will send transactional emails are the correct times and that those emails are actually delivered! This is fantastic!

Wrapping it all up

In summary, transactional emails are an important part of many applications. Doing so with AWS SES is a great way to gain more control over other services like MailChimp and MailGun. However, which ever solution you choose remember to test your transactional email sending and receiving with real email addresses. MailSlurp makes that easy and automated so you know for sure that your app is sending and receiving what it should.

I hope that helped!

Thanks,

Jack from MailSlurp