Official client for MailSlurp Email and SMS API. Create email addresses and phone numbers in Javascript without a mail server. Send and receive real emails in applications or tests.
npm install mailslurp-clientCreate real email addresses on demand. Send and receive emails and attachments from code and tests using Javascript or Typescript. Use real phone numbers to process inbound TXT messages.
MailSlurp is an email and SMS API service that lets you create real email addresses in code. You can then send and receive emails and attachments in Javascript applications and tests. You can also create phone numbers and fetch inbound SMS.
MailSlurp is free for personal use but requires an API KEY. Please see the getting started guide for an introduction on key MailSlurp concepts or continue reading.
npm install --save mailslurp-client or yarn add mailslurp-client``javascript
// import mailslurp-client
const MailSlurp = require('mailslurp-client').default;
// OR import { MailSlurp } from "mailslurp-client"
// create a client
const apiKey = process.env.API_KEY ?? 'your-api-key';
const mailslurp = new MailSlurp({ apiKey });
// create an inbox
const inbox = await mailslurp.inboxController.createInbox({});
expect(inbox.emailAddress).toContain('@mailslurp');
`
More usage examples are included below.
- Main class methods
- Method Documentation
- NPM Package
- REST API Docs
- GraphQL Client
- Github Source
This section describes how to get up and running with the Javascript client.
See the guides page for more examples and use with common frameworks. For use with CypressJS see the official Cypress MailSlurp plugin.
See the method documentation for a list of all functions.
> See the test/integration.spec.ts in this package for usage examples of this client.
First you'll need an API Key. Create a free account and copy the key from your dashboard.
Install MailSlurp using NPM (NodeJS) or by including the source code in your project.
`bash`
npm install --save mailslurp-client
javascript
const MailSlurp = require("mailslurp-client").default;
// or
import { MailSlurp } from "mailslurp-client";
`$3
Create a MailSlurp instance by instantiating a class with your API Key.
javascript
const mailslurp = new MailSlurp({ apiKey: "your_api_key" });
`
#### Timeouts
MailSlurp API endpoints are built to hold a connection open if the query is told to wait for certain conditions - like a new email arriving. For this reason it is important to use appropriate timeouts in tests or when settings up a fetch client.
> MailSlurp recommends a 60_000 ms timeout to ensure emails arrive consistently. SMTP is a slow protocol so you may need to allow time for emails to arrive.
#### Fetch settings
MailSlurp is built on Javascript
. If you want to override the default fetch client you can do so when configuring MailSlurp.`typescript
const { MailSlurp } = require('mailslurp-client');
const crossFetch = require('cross-fetch');
const mailslurp = new MailSlurp({
fetchApi: crossFetch,
apiKey: apiKey,
});
`#### Fetch handling exceptions
Any method that returns non-2xx response throws an exception by default (unless you use methods with the
suffix). There are valid 404 responses that you should handle, these include the 408 returned from waitFor methods when the required matching emails could not be found.-
4xx (400, 404...) response codes indicate a client error. Access the error message on the response body
- 5xx (500, 501...) response codes indicate a server error. If encountered please contact support.`typescript
try {
await mailslurp.waitController.waitForLatestEmail({
inboxId: inboxId,
timeout: timeout,
unreadOnly: true,
});
} catch (e) {
// handle the error and status code in your code
const statusCode = e.status;
const errorMessage = await e.text(); expect(errorMessage).toContain('Failed to satisfy email query for inbox');
expect(statusCode).toEqual(408);
}
`#### Fetch without exceptions (using ApiResponse)
If you prefer not to use
you can use methods with the Raw suffix. These methods return an ApiResponse that includes a status and result instead of throwing exceptions.`typescript
// use methods with Raw suffix to access a wrapped response
// that contains the status instead of throwing an exception
const inboxRaw: ApiResponse =
await mailslurp.inboxController.createInboxRaw({});
expect(inboxRaw.raw.ok).toBeTruthy();
const inbox = await inboxRaw.value();
expect(inbox.id).toBeTruthy();
`$3
Note the object is a class with many common methods. It does not contain all MailSlurp API methods. The full API is available as individually exported controllers.See the MailSlurp class documentation for all methods or
see the
test/integration.spec.ts file for usage examples. You can also instantiate controllers directly. See the API controllers for method details.`javascript
// controllers are available on a MailSlurp instance
const { MailSlurp } = require('mailslurp-client');
const mailslurp = new MailSlurp({ apiKey });
await mailslurp.inboxController.createInbox({});
// or by import controllers and instantiating with a configuration
const { InboxControllerApi } = require('mailslurp-client');
const inboxController = new InboxControllerApi(new Configuration({ apiKey }));
await inboxController.createInbox({});
`Email usage examples
Here are some snippets of common usage.
$3
MailSlurp inboxes have real email addresses. There are several ways to create them. See the docs for full inbox object reference.
Inboxes can be either or HTTP type mailboxes. HTTP inboxes are powered by AWS SES and are great for most use cases. SMTP inboxes use a custom mail server running at mx.mailslurp.com to support older email clients. SMTP inboxes are more suitable for public facing usage.#### Simple usage
You can create an inbox with a randomly assigned email address ending in
@mailslurp.com like so:`javascript
const inbox = await mailslurp.createInbox();
// { id: '123', emailAddress: '123@mailslurp.com' }
`#### Create inbox options
Use the
or methods on the inboxController property to create email addresses using more options.`javascript
await mailslurp.inboxController.createInbox({});
`> To use custom domains see the domain verification guide
$3
Inboxes have real email addresses. See the inbox reference for all properties.javascript
const mailslurp = new MailSlurp(config);
const { id: inboxId } = await mailslurp.createInbox();
const inbox = await mailslurp.getInbox(inboxId);
expect(inbox.id).toEqual(inboxId);
`$3
You can access SMTP_INBOX type inboxes using an SMTP client like nodemailer. First create an inbox then call the function to obtain SMTP username and password:`javascript
const {MailSlurp} = require('mailslurp-client');
const nodemailer = require("nodemailer");
const apiKey = process.env.API_KEY;
const mailslurp = new MailSlurp({ apiKey });// get access details for smpt server
const server = await mailslurp.getImapSmtpAccessDetails();
// use details to configure SMTP client like NodeMailer
const opts = {
host: server.smtpServerHost,
port: server.smtpServerPort,
secure: false, // Disable tls recommended
auth: {
user: server.smtpUsername,
pass: server.smtpPassword,
type: "PLAIN" // Note the use of PLAIN AUTH
},
}
const transport = nodemailer.createTransport(opts)
`$3
Inbox lists are paginated and sortable. List methods return a projection of an inbox. See the inbox projection reference for properties.javascript
const mailslurp = new MailSlurp(config);// get paginated inboxes
const [index, size] = [0, 20];
const pageInboxes = await mailslurp.getAllInboxes(0, 20);
expect(pageInboxes.size).toEqual(size);
expect(pageInboxes.number).toEqual(index);
`$3
To read emails that already exist in an inbox use the EmailController method. To wait for expected emails that may not have arrived yet use the WaitForController.There are many ways to receive and fetch emails in MailSlurp. Emails have many properties including body, subject, attachments and more. See the API docs for full email reference.
`javascript
const inbox = await mailslurp.createInbox();
await mailslurp.sendEmail(inbox.id, {
to: [inbox.emailAddress],
subject: 'test',
});// wait for first email
const latestEmail = await mailslurp.waitForLatestEmail(inbox.id, timeoutMs);
expect(latestEmail.subject).toContain('test');
// send another
await mailslurp.sendEmail(inbox.id, {
to: [inbox.emailAddress],
subject: 'second',
});
// wait for second using controller instead
const secondEmail = await mailslurp.waitController.waitForLatestEmail({
inboxId: inbox.id,
unreadOnly: true,
});
expect(secondEmail.subject).toContain('second');
const allEmails = await mailslurp.getEmails(inbox.id);
expect(allEmails).toHaveLength(2);
`For more fetching methods see the WaitForController and the EmailController
$3
To send emails use the SendEmailOptions arguments with the InboxController or MailSlurp instance methods.typescript
const inbox = await mailslurp.createInbox();
const options = {
to: [emailAddress],
subject: 'Hello',
body: 'Welcome',
};
const sent = await mailslurp.sendEmail(inbox.id, options);
expect(sent.subject).toContain('Hello');
`#### Sending with queues
If your plan permits you can send emails using a queue. This allows you to safely recover emails that failed to send and retry them. Use queue to ensure that emails are always delivered regardless of your account status, bounce limit, or payment failures.
typescript
await mailslurp.inboxController.sendEmailWithQueue({
inboxId: inboxId,
sendEmailOptions: {
to: [recipient],
subject: 'Sent with a queue',
body:
'Use queues to allow recovery of failed email ' +
'sending when account reaches limits or has payment issues',
},
// validate before adding to queue to fail early
validateBeforeEnqueue: false,
});
`$3
Validate an email address to find out if it exists and can receive email. This can help reduce your bounce rate and improve your sending reputation.javascript
const mailslurp = new MailSlurp(config);
const res =
await mailslurp.emailVerificationController.validateEmailAddressList({
validateEmailAddressListOptions: {
emailAddressList: ['contact@mailslurp.dev', 'bad@mailslurp.dev'],
},
});
expect(res.resultMapEmailAddressIsValid['contact@mailslurp.dev']).toEqual(
true
);
expect(res.resultMapEmailAddressIsValid['bad@mailslurp.dev']).toEqual(
false
);
`$3
Upload attachment using the AttachmentController.Attachments can be uploaded as base64 strings. The ids returned can be used with
send functions. See the upload attachment options for more information.`javascript
const mailslurp = new MailSlurp(config);// read a file as a base64 encoded string
const pathToAttachment = path.join(__dirname + '/attachment.txt');
const fileBase64Encoded = await fs.promises.readFile(pathToAttachment, {
encoding: 'base64',
});
// upload the attachment as base64 string and get atttachment id
const [attachmentId] =
await mailslurp.attachmentController.uploadAttachment({
uploadAttachmentOptions: {
base64Contents: fileBase64Encoded,
contentType: 'text/plain',
filename: path.basename(pathToAttachment),
},
});
`$3
To send an attachment first upload the file using the AttachmentController then send an email containing the attachment ID with the InboxController.You can send attachments by including their IDs in the attachments options when sending.
javascript
const inbox1 = await mailslurp.createInbox();
const inbox2 = await mailslurp.createInbox();// send email and get saved result
const sentEmail = await mailslurp.inboxController.sendEmailAndConfirm({
inboxId: inbox1.id,
sendEmailOptions: {
to: [inbox2.emailAddress],
attachments: [attachmentId],
subject: 'Send attachments',
body: 'Here are your files',
},
});
expect(sentEmail.attachments.length).toEqual(1);
`$3
To wait for expected emails to arrive and read their contents use the WaitFor controller endpoints.javascript
// first wait for an email
const email = await mailslurp.waitController.waitForLatestEmail({
inboxId: inboxId,
timeout: 30000,
unreadOnly: true,
});// check has attachments
expect(email.attachments.length).toEqual(1);
// download with email controller as base64 string
const attachmentDto =
await mailslurp.emailController.downloadAttachmentBase64({
attachmentId: email.attachments[0]!!,
emailId: email.id,
});
// can access content
expect(attachmentDto.base64FileContents).toBeTruthy();
const fileContent = new Buffer(
attachmentDto.base64FileContents,
'base64'
).toString();
expect(fileContent).toContain('test');
// can access size etc
expect(attachmentDto.sizeBytes).toBeTruthy();
expect(attachmentDto.contentType).toBeTruthy();
`$3
The WaitForController contains many methods for waiting for emails to arrive in an inbox. See the waitFor controller reference for more information.javascript
it('can wait for multiple emails', async () => {
const mailslurp = new MailSlurp(config); // example of creating inboxes simultaneously
const inbox1 = await mailslurp.createInbox();
const inbox2 = await mailslurp.createInbox();
// send two emails
await mailslurp.sendEmail(inbox1.id, {
to: [inbox2.emailAddress],
subject: 'Hello Dogs',
});
await mailslurp.sendEmail(inbox1.id, {
to: [inbox2.emailAddress],
subject: 'Hello Cats',
});
// wait for 2 emails
const emails = await mailslurp.waitController.waitForEmailCount({
count: 2,
inboxId: inbox2.id,
sort: WaitForEmailCountSortEnum.DESC,
});
const subjects = emails.map((e) => e.subject);
expect(subjects).toContain('Hello Dogs');
expect(subjects).toContain('Hello Cats');
});
`$3
MailSlurp allows one to wait for emails that match certain parameters. Here is an example:javascript
const inbox1 = await mailslurp.createInbox();
const inbox2 = await mailslurp.createInbox();// specify recipient (must be array)
const to = [inbox2.emailAddress];
// send two emails
await mailslurp.sendEmail(inbox1.id, { to, subject: 'Apples' });
await mailslurp.sendEmail(inbox1.id, { to, subject: 'Oranges' });
// wait for matching email based on subject (see MatchOptions for all options)
const matchOptions: MatchOptions = {
matches: [
{
field: MatchOptionFieldEnum.SUBJECT,
should: MatchOptionShouldEnum.CONTAIN,
value: 'Apples',
},
],
};
const expectCount = 1;
const matchingEmails = await mailslurp.waitController.waitForMatchingEmails(
{
inboxId: inbox2.id,
matchOptions: matchOptions,
count: expectCount,
timeout: timeoutMillis,
unreadOnly: true,
}
);
expect(matchingEmails.length).toEqual(1);
expect(matchingEmails[0].subject).toEqual('Apples');
`See the MatchOptions documentation for reference.
$3
You can extract useful information from emails using regular expressions. See the EmailController for more information:javascript
const inbox1 = await mailslurp.createInbox();
const inbox2 = await mailslurp.createInbox();const to = [inbox2.emailAddress];
const body = 'Hi there. Your code is: 123456';
await mailslurp.sendEmail(inbox1.id, { to, body });
// wait for email
const email = await mailslurp.waitController.waitForLatestEmail({
inboxId: inbox2.id,
timeout: timeoutMillis,
unreadOnly: true,
});
const pattern = 'code is: ([0-9]{6})';
expect(email.body).toContain('Your code is');
// pass the pattern to mailslurp to match for emails
const result = await mailslurp.emailController.getEmailContentMatch({
contentMatchOptions: { pattern },
emailId: email.id,
});
// access the match groups
expect(result.matches).toHaveLength(2);
expect(result.matches[0]).toEqual('code is: 123456');
expect(result.matches[1]).toEqual('123456');
`Phone SMS/TXT usage
MailSlurp supports inbound SMS using real phone numbers. See the SMS guide or the developer documentation to get started.$3
Phone numbers must be created in the MailSlurp dashboard. Once you create a number you can use it in code.$3
Fetch phone numbers with the phone controller.typescript
const {
content: [phone],
} = await mailslurp.phoneController.getPhoneNumbers({
phoneCountry: GetPhoneNumbersPhoneCountryEnum.US,
});
expect(phone.phoneNumber).toContain('+1');
`$3
Use the wait for controller to wait for inbound SMS messages:typescript
const sms = await mailslurp.waitController.waitForLatestSms({
waitForSingleSmsOptions: {
phoneNumberId: phone.id,
timeout: 30_000,
unreadOnly: true,
},
});
expect(sms.body).toContain('Here is your code');
expect(sms.fromNumber).toEqual('+13252527014');
`You can also use webhooks with the
event to receive text messages.Testing
MailSlurp is testing email and SMS in code. Testing can include the analysis of email content, feature support, and the sending and receiving of emails and SMS to test applications and processes. MailSlurp can be used with common test frameworks.$3
- Testing guide
- Cypress
- Playwright
- Selenium$3
Check rendering of email HTML, CSS, and images across different devices and mail clients. MailSlurp can analyze your emails and detect HTML, CSS, and image features that may not be supported by all email clients. `typescript
const { result } =
await mailslurp.emailController.checkEmailBodyFeatureSupport({
emailId: email.id,
});
expect(result.detectedFeatures).toContain(
EmailFeatureSupportResultDetectedFeaturesEnum.html_doctype
);
expect(
result.featurePercentages.find(
(it) =>
it.status === EmailFeatureSupportStatusPercentageStatusEnum.SUPPORTED
)?.percentage
).toBeGreaterThan(50);
`$3
You can parse emails and detect 404s and broken links. MailSlurp will attempt to call the resource to ensure it exists. Check for dead links like this:typescript
const result = await mailslurp.emailController.checkEmailBody({
emailId: email.id,
});
expect(result.hasIssues).toEqual(true);
expect(result.linkIssues.length).toEqual(1);
expect(result.linkIssues[0].url).toEqual(
'https://api.mailslurp.com/not-existing'
);
`$3
Broken images can be detected in emails. MailSlurp will attempt to load the image and detect if it is missing. Check for missing images like this:typescript
const result = await mailslurp.emailController.checkEmailBody({
emailId: email.id,
});
expect(result.hasIssues).toEqual(true);
expect(result.imageIssues.length).toEqual(1);
expect(result.imageIssues[0].url).toEqual(
'https://www.mailslurp.com/broken-image.png'
);
`See the content testing guide for more information.
Webhooks
To have received emails sent to your server using HTTP webhook push create a webhook using the WebhookController or see the webhook email guide.$3
You can create webhooks in code or using the MailSlurp dashboard.typescript
await mailslurp.webhookController.createWebhook({
inboxId,
webhookOptions: {
url: "https://my-server.com/webhook",
eventName: CreateWebhookOptionsEventNameEnum.NEW_EMAIL
}
})
`$3
To consume webhooks first create a webhook for an inbox and a given webhook event. Set the webhook URL to an endpoint on your server. Your server must be publicly accessible and return a 200 or 201 status code in 30 seconds. To test locally use a service like ngrok.io to tunnel your local machine to a public URL. The payload posted to your end point will depend on the event type. Here is a listen example using express> Note: you can use any framework or language you like with webhooks.
typescript
// example express server that you control
const app = express();
app.use(bodyParser.json());
// receive new email webhook payload via post
app.post('/new-email-endpoint', async (request, response) => {
// can use typescript types
const payload = request.body as WebhookNewEmailPayload; // do something with with email id
expect(payload.emailId).toBeTruthy();
// return a 2xx status code so MailSlurp knows you received it
return response.sendStatus(200);
});
const server = app.listen(port);
`$3
typescript
// get a test payload for NEW_EMAIL event
const testPayload =
await mailslurp.webhookController.getTestWebhookPayloadNewEmail();
// post payload to your server to test it
const testResponse = await fetch(
http://localhost:${port}/new-email-endpoint,
{
method: 'POST',
headers: {
'content-type': 'application/json',
},
body: JSON.stringify(testPayload),
}
);
// expect 200
expect(testResponse.status).toEqual(200);
``- Webhook documentation
- Method documentation
- Guides
- API Key
- Example repositories
- Dashboard App
- Documentation
- Github
- NPM package