GraphQL API for disposable email accounts

Did you know you can use GraphQL to send and receive emails? That's right - there is a free API at graphql.mailslurp.com you can use to create disposable email accounts for testing and application development.

Create a test project

Use NPM to initialize a new node project and add the AVA test library (you can use any test library you wish).

npm init ava -y

Then add the graphql-request library so we can call the GraphQL endpoints.

npm install --save graphql-request

Our package json now looks something like this:

{
  "name": "graphql",
  "version": "1.0.0",
  "description": "MailSlurp graphql usage example",
  "main": "index.js",
  "scripts": {
    "test": "ava"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "ava": "^4.0.0"
  },
  "dependencies": {
    "graphql-request": "^3.7.0"
  }
}

To use ESM style imports add the type: module flag to your package.

{
  "main": "index.mjs",
  "type":  "module"
}

Configure a graphql client for email accounts

Create an index.mjs file and add the code below:

import {GraphQLClient} from "graphql-request";

export function getClient(apiKey) {
  // create a new graphql-request client using the MailSlurp graphql endpoint
  // and passing a headers map including your MailSlurp API Key using "x-api-key" header
  return new GraphQLClient('https://graphql.mailslurp.com', {
    headers: {
      'x-api-key': apiKey,
    },
  });
}

Testing disposable email accounts with AVA

Now we have a client let us write some tests to demonstrate usage of email accounts. Create a file test.mjs and add a test.

import test from 'ava';

test('bar', async t => {
	const bar = Promise.resolve('bar');
	t.is(await bar, 'bar');
});

If we run npm t we will see passing tests in your console output.

npm run test

> graphql@1.0.0 test
> ava


  ✔ bar
  ─

  1 test passed

Given that the dummy tests are passing we can add gql queries to our test to create a disposable email account, send and email to it and receive said email.

Create an email address with GraphQL

Create a new disposable email account using MailSlurp's createInbox mutation. Use a custom domain for permanent inboxes.

import test from 'ava';
import {gql} from "graphql-request";
import {getClient} from "./index.mjs";

const apiKey = process.env.API_KEY;

test('can create inbox', async t => {
    const {createInbox} = await getClient(apiKey).request(gql`
        mutation {
            createInbox {
                id
                emailAddress
            }
        }
    `);
    t.is(!!createInbox.id, true);
    t.is(createInbox.emailAddress.indexOf('@mailslurp') > -1, true);
});

Send emails

test('can send an email', async t => {
    // create an inbox
    const {createInbox} = await getClient(apiKey).request(gql`
        mutation {
            createInbox {
                id
                emailAddress
            }
        }
    `);
    // send an email using mutation
    const {sendEmail} = await getClient(apiKey).request(gql`
        mutation {
            sendEmail(fromInboxId: "${createInbox.id}", to: ["${createInbox.emailAddress}"], subject: "Test subject") {
                from
                to
                subject
            }
        }
    `);
    t.is(sendEmail.from, createInbox.emailAddress)
    t.is(sendEmail.subject, "Test subject")
    t.is(sendEmail.to.indexOf(createInbox.emailAddress) > -1, true)
});

Receive and read emails in GraphQL

test('can send an email and receive the contents', async t => {
    // create an inbox
    const {createInbox} = await getClient(apiKey).request(gql`
        mutation {
            createInbox {
                id
                emailAddress
            }
        }
    `);
    // send an email using mutation
    const {sendEmail} = await getClient(apiKey).request(gql`
        mutation {
            sendEmail(fromInboxId: "${createInbox.id}", to: ["${createInbox.emailAddress}"], subject: "Test subject", body: "Hello") {
                from
                to
                subject
            }
        }
    `);

    // wait for the email to arrive
    const {waitForLatestEmail} = await getClient(apiKey).request(gql`
        query {
            waitForLatestEmail(inboxId: "${createInbox.id}", timeout: 60000, unreadOnly: true) {
                id
                from
                to
                subject
                body
            }
        }
    `);
    t.is(waitForLatestEmail.body.indexOf("Hello") > -1 , true)
    t.is(waitForLatestEmail.subject.indexOf(sendEmail.subject) > -1 , true)
    t.is(waitForLatestEmail.from.indexOf(sendEmail.from) > -1 , true)

    // delete the email afterwards
       const {deleteEmail} = await getClient(apiKey).request(gql`
        mutation {
            deleteEmail(emailId: "${waitForLatestEmail.id}")
        }
    `);
    t.is(deleteEmail === "deleted", true)

});