|
| 1 | +# MailSlurp GraphQL Email API |
| 2 | + |
| 3 | +MailSlurp has a powerful free GraphQL email API that lets you fetch and read emails with GraphQL in React, Apollo, iOS, Android or server to server. You can create disposable test email accounts on demand or permanent custom domains. Send and receive emails and attachments from any client that uses GraphQL. |
| 4 | + |
| 5 | +If you are unfamiliar with GraphQL don't worry - MailSlurp has a traditional [REST API](https://docs.mailslurp.com/api/) and [compiled SDK Clients](https://www.mailslurp.com/developers/) in many languages. |
| 6 | + |
| 7 | +## Quick links |
| 8 | +- API server root is [https://graph.mailslurp.com/](https://graph.mailslurp.com/) |
| 9 | +- See the Github for [graphql schema definitions](https://github.com/mailslurp/mailslurp-client-graphql/blob/master/mailslurp/) |
| 10 | +- Go to the [MailSlurp GraphQL Playground](https://graphql.mailslurp.com) to explore yourself |
| 11 | +- Read the [graphQL getting started guide](https://www.mailslurp.com/guides/graphql-email-api/) for more help |
| 12 | + |
| 13 | +## Getting started |
| 14 | +MailSlurp's API is free but requires an API_KEY. [Obtain an API_KEY](https://app.mailslurp.com) at app.mailslurp.com first. **Include you api key in an `x-api-key` header** to authenticate you requests. |
| 15 | + |
| 16 | +### HTTP requests |
| 17 | +You can query the GraphQL api using any client. Here is an example using Curl in a terminal: |
| 18 | + |
| 19 | +```bash |
| 20 | +curl -lX POST https://graphql.mailslurp.com -H 'x-api-key:YOUR_API_KEY' -H "Content-Type: application/json" -d '{ "query": "{ inboxes { totalElements } }"}' |
| 21 | +``` |
| 22 | + |
| 23 | +For simpler usage please see the Javascript examples. |
| 24 | + |
| 25 | +### Javascript usage |
| 26 | +Add the `graphql-request` library to your node project. |
| 27 | + |
| 28 | +```bash |
| 29 | +npm install --save graphql-request |
| 30 | +``` |
| 31 | + |
| 32 | +Create a client using the `https://graphql.mailslurp.com` root endpoint and pass your api key as a header. |
| 33 | + |
| 34 | +```javascript |
| 35 | +import {GraphQLClient} from "graphql-request"; |
| 36 | + |
| 37 | +export function getClient(apiKey) { |
| 38 | + if (!apiKey) { |
| 39 | + throw "Please set missing API_KEY" |
| 40 | + } |
| 41 | + // create a new graphql-request client using the MailSlurp graphql endpoint |
| 42 | + // and passing a headers map including your MailSlurp API Key using "x-api-key" header |
| 43 | + return new GraphQLClient('https://graphql.mailslurp.com', { |
| 44 | + headers: { |
| 45 | + 'x-api-key': apiKey, |
| 46 | + }, |
| 47 | + }); |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +## Create email inbox |
| 52 | +Using the client function we created above we can create a new email address using the `createInbox` mutation. |
| 53 | + |
| 54 | +Note: the examples that follow use the AVA test framework to demonstrate usage - you can use any frameworks you wish with GraphQL. |
| 55 | + |
| 56 | +```javascript |
| 57 | +import test from 'ava'; |
| 58 | +import {gql} from "graphql-request"; |
| 59 | +import {getClient} from "./index.mjs"; |
| 60 | + |
| 61 | +const apiKey = process.env.API_KEY; |
| 62 | + |
| 63 | +test('can create inbox', async t => { |
| 64 | + const {createInbox} = await getClient(apiKey).request(gql` |
| 65 | + mutation { |
| 66 | + createInbox { |
| 67 | + id |
| 68 | + emailAddress |
| 69 | + } |
| 70 | + } |
| 71 | + `); |
| 72 | + t.is(!!createInbox.id, true); |
| 73 | + t.is(createInbox.emailAddress.indexOf('@mailslurp') > -1, true); |
| 74 | +}); |
| 75 | +``` |
| 76 | + |
| 77 | +## Send email in GraphQL |
| 78 | + |
| 79 | +Use the `sendEmail` mutation to send a real email from your inbox. |
| 80 | + |
| 81 | +```javascript |
| 82 | +test('can send an email', async t => { |
| 83 | + // create an inbox |
| 84 | + const {createInbox} = await getClient(apiKey).request(gql` |
| 85 | + mutation { |
| 86 | + createInbox { |
| 87 | + id |
| 88 | + emailAddress |
| 89 | + } |
| 90 | + } |
| 91 | + `); |
| 92 | + // send an email using mutation |
| 93 | + const {sendEmail} = await getClient(apiKey).request(gql` |
| 94 | + mutation { |
| 95 | + sendEmail(fromInboxId: "${createInbox.id}", to: ["${createInbox.emailAddress}"], subject: "Test subject") { |
| 96 | + from |
| 97 | + to |
| 98 | + subject |
| 99 | + } |
| 100 | + } |
| 101 | + `); |
| 102 | + t.is(sendEmail.from, createInbox.emailAddress) |
| 103 | + t.is(sendEmail.subject, "Test subject") |
| 104 | + t.is(sendEmail.to.indexOf(createInbox.emailAddress) > -1, true) |
| 105 | +}); |
| 106 | +``` |
| 107 | + |
| 108 | +## Receive and read email using GraphQL |
| 109 | +You can query emails that you know already exist using the `email` and `emails` queries. To block until an expected email either arrives or is found in an inbox use the `waitForX` queries: |
| 110 | + |
| 111 | +```javascript |
| 112 | +test('can send an email and receive the contents', async t => { |
| 113 | + // create an inbox |
| 114 | + const {createInbox} = await getClient(apiKey).request(gql` |
| 115 | + mutation { |
| 116 | + createInbox { |
| 117 | + id |
| 118 | + emailAddress |
| 119 | + } |
| 120 | + } |
| 121 | + `); |
| 122 | + // send an email using mutation |
| 123 | + const {sendEmail} = await getClient(apiKey).request(gql` |
| 124 | + mutation { |
| 125 | + sendEmail(fromInboxId: "${createInbox.id}", to: ["${createInbox.emailAddress}"], subject: "Test subject", body: "Hello") { |
| 126 | + from |
| 127 | + to |
| 128 | + subject |
| 129 | + } |
| 130 | + } |
| 131 | + `); |
| 132 | + |
| 133 | + // wait for the email to arrive |
| 134 | + const {waitForLatestEmail} = await getClient(apiKey).request(gql` |
| 135 | + query { |
| 136 | + waitForLatestEmail(inboxId: "${createInbox.id}", timeout: 60000, unreadOnly: true) { |
| 137 | + id |
| 138 | + from |
| 139 | + to |
| 140 | + subject |
| 141 | + body |
| 142 | + } |
| 143 | + } |
| 144 | + `); |
| 145 | + t.is(waitForLatestEmail.body.indexOf("Hello") > -1 , true) |
| 146 | + t.is(waitForLatestEmail.subject.indexOf(sendEmail.subject) > -1 , true) |
| 147 | + t.is(waitForLatestEmail.from.indexOf(sendEmail.from) > -1 , true) |
| 148 | + |
| 149 | + // delete the email afterwards |
| 150 | + const {deleteEmail} = await getClient(apiKey).request(gql` |
| 151 | + mutation { |
| 152 | + deleteEmail(emailId: "${waitForLatestEmail.id}") |
| 153 | + } |
| 154 | + `); |
| 155 | + t.is(deleteEmail === "deleted", true) |
| 156 | + |
| 157 | +}); |
| 158 | +``` |
0 commit comments