{"id":15696,"library":"mailslurp-client","title":"MailSlurp Client for Email and SMS API","description":"MailSlurp Client is the official JavaScript and TypeScript library for interacting with the MailSlurp Email and SMS API. It enables developers to programmatically create on-demand email addresses and phone numbers without managing a mail server, facilitating sending and receiving real emails and SMS messages directly from applications or automated tests. The library is currently stable at version 17.2.0 and maintains a regular release cadence. Its key differentiator is providing a fully functional, programmatic interface to an email and SMS infrastructure, making it ideal for robust end-to-end testing of communication workflows. It supports handling attachments, setting custom timeouts for message arrival, and offers both CommonJS and ES module import patterns. The client integrates with the standard `fetch` API and allows for custom `fetch` implementations.","status":"active","version":"17.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/mailslurp/mailslurp-client","tags":["javascript","email","smtp","test","e2e","phone","sms","ai","integration","typescript"],"install":[{"cmd":"npm install mailslurp-client","lang":"bash","label":"npm"},{"cmd":"yarn add mailslurp-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add mailslurp-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For CommonJS environments, `require('mailslurp-client').default` is typically needed to access the main `MailSlurp` class. Native ESM `import { MailSlurp }` is the standard for modern projects.","wrong":"const MailSlurp = require('mailslurp-client')","symbol":"MailSlurp","correct":"import { MailSlurp } from 'mailslurp-client'"},{"note":"Represents the controller for managing email inboxes. Other controllers like `SendController` or `WaitForController` are also available as named exports.","wrong":"import InboxController from 'mailslurp-client'","symbol":"InboxController","correct":"import { InboxController } from 'mailslurp-client'"},{"note":"Explicit type import for configuring inbox creation. Essential for TypeScript users to get correct type inference and auto-completion.","symbol":"CreateInboxOptions","correct":"import type { CreateInboxOptions } from 'mailslurp-client'"}],"quickstart":{"code":"import { MailSlurp } from 'mailslurp-client';\n\n// Assuming a test runner like Jest is present for 'expect'\n// In a standalone script, you might use console.assert or a custom check.\nconst expect = (value: any) => ({\n  toContain: (substring: string) => {\n    if (typeof value !== 'string' || !value.includes(substring)) {\n      throw new Error(`Expected \"${value}\" to contain \"${substring}\"`);\n    }\n  },\n  toEqual: (expected: any) => {\n    if (value !== expected) {\n      throw new Error(`Expected \"${value}\" to equal \"${expected}\"`);\n    }\n  }\n});\n\nasync function runMailSlurpExample() {\n  // Retrieve API Key from environment variables or provide directly\n  const apiKey = process.env.MAILSLURP_API_KEY ?? 'YOUR_MAILSLURP_API_KEY';\n  if (apiKey === 'YOUR_MAILSLURP_API_KEY') {\n    console.warn('WARNING: Replace \"YOUR_MAILSLURP_API_KEY\" with your actual MailSlurp API Key from mailslurp.com dashboard.');\n    return;\n  }\n\n  // Create a new MailSlurp client instance\n  const mailslurp = new MailSlurp({ apiKey });\n\n  console.log('Creating a new MailSlurp inbox...');\n  // Create a new random inbox for testing\n  const inbox = await mailslurp.inboxController.createInbox({});\n\n  console.log(`Inbox created with email address: ${inbox.emailAddress}`);\n  // Assert that the email address is valid\n  expect(inbox.emailAddress).toContain('@');\n\n  // Example: Send an email from the created inbox\n  const recipientEmail = 'test-recipient@example.com'; // In a real scenario, this could be another MailSlurp inbox\n  const emailSubject = 'Hello from MailSlurp!';\n  await mailslurp.sendController.sendEmailAndConfirm({\n    inboxId: inbox.id,\n    sendEmailOptions: {\n      to: [recipientEmail],\n      subject: emailSubject,\n      body: 'This is a test email sent using the MailSlurp client.',\n    },\n  });\n  console.log(`Email sent from ${inbox.emailAddress} to ${recipientEmail}`);\n\n  // To demonstrate receiving, let's assume `recipientEmail` is another MailSlurp inbox you control\n  // Or if sending to itself for loopback test (not typical, but for demonstration):\n  // const receivedEmail = await mailslurp.waitForController.waitForLatestEmail({\n  //   inboxId: inbox.id,\n  //   timeout: 60000,\n  // });\n  // console.log(`Received email with subject: \"${receivedEmail.subject}\"`);\n  // expect(receivedEmail.subject).toEqual(emailSubject);\n  console.log('MailSlurp client initialized and inbox created/sent email. Check your MailSlurp dashboard.');\n}\n\nrunMailSlurpExample().catch(console.error);\n","lang":"typescript","description":"This example demonstrates initializing the MailSlurp client with an API key, creating a temporary email inbox, sending an email from that inbox, and includes a placeholder for demonstrating email reception. It highlights common use cases for automated email testing and integration workflows."},"warnings":[{"fix":"Set appropriate timeouts for API calls, especially `waitForController` methods. The recommended timeout is 60,000 ms (60 seconds) or more for consistent email arrival.","message":"MailSlurp API operations, especially waiting for emails (`waitForController`), are designed to hold connections open and require sufficient timeouts. SMTP is an inherently slow protocol, and short timeouts can lead to test failures or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `apiKey` is correctly provided during `MailSlurp` client instantiation. Obtain a key from the MailSlurp dashboard (mailslurp.com).","message":"An API Key is mandatory for all MailSlurp operations. Failing to provide a valid key will result in authentication errors and prevent any API calls from succeeding.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For ES Modules, use `import { MailSlurp } from 'mailslurp-client';`. For CommonJS, use `const MailSlurp = require('mailslurp-client').default;` to access the primary class.","message":"The MailSlurp client supports both CommonJS (`require`) and ES Module (`import`) syntax. Developers commonly make mistakes in combining these or using the wrong pattern for their environment, e.g., `require('pkg')` instead of `require('pkg').default` for the main class in CJS.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"If overriding `fetch`, consider using a well-maintained polyfill such as `cross-fetch` to ensure consistent and complete `fetch` API functionality across different JavaScript environments.","message":"While the client allows overriding the default `fetch` implementation, using a non-standard or incomplete polyfill in Node.js environments can lead to unexpected behavior or missing features compared to a robust solution like `cross-fetch`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Obtain your API Key from the MailSlurp dashboard (app.mailslurp.com) and pass it to the client: `const mailslurp = new MailSlurp({ apiKey: process.env.MAILSLURP_API_KEY });`","cause":"The `apiKey` option was not provided or was empty when instantiating `new MailSlurp({ apiKey: '...' })`.","error":"MailSlurp API Key not found. Please provide an API Key to the MailSlurp client."},{"fix":"Increase the `timeout` parameter for the specific MailSlurp operation, or globally configure the fetch client's timeout. SMTP can be slow, so 60-120 seconds might be necessary for reliability.","cause":"An API call, particularly a `waitForController` method, waited longer than the specified timeout for a condition (e.g., email arrival) to be met.","error":"Error: Timeout of 60000ms exceeded"},{"fix":"For ES Modules: `import { MailSlurp } from 'mailslurp-client';`. For CommonJS: `const MailSlurp = require('mailslurp-client').default;`.","cause":"Incorrect import statement for `MailSlurp` class. This typically indicates a mismatch between the module system being used (CommonJS vs. ESM) and the import syntax.","error":"TypeError: (0 , mailslurp_client__WEBPACK_IMPORTED_MODULE_0__.MailSlurp) is not a constructor"}],"ecosystem":"npm"}