{"library":"mailpit-api","title":"Mailpit API Client","description":"The `mailpit-api` package provides a robust TypeScript client for programmatically interacting with the Mailpit REST API. It enables developers to automate email testing workflows in various JavaScript environments, including Node.js, browsers, and modern JS runtimes, making it ideal for end-to-end (E2E) testing with frameworks like Playwright. The current stable version is 1.9.0, with minor releases and patch fixes occurring frequently, often driven by dependency updates and feature enhancements such as WebSocket support for real-time event listening. Key differentiators include its TypeScript-first design, comprehensive documentation, and specific utilities for common testing scenarios like waiting for messages to arrive, clearing mailboxes, and inspecting email content, all while maintaining compatibility across diverse JavaScript ecosystems. It simplifies the integration of email verification into automated test suites by abstracting the raw Mailpit API calls.","language":"javascript","status":"active","last_verified":"Sun Apr 19","install":{"commands":["npm install mailpit-api"],"cli":null},"imports":["import { MailpitClient } from 'mailpit-api';","import type { MailpitMessage } from 'mailpit-api';","const message = await mailpit.waitForMessage({ query: 'subject:Test' });"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import { MailpitClient } from \"mailpit-api\";\nimport { expect } from \"@playwright/test\";\n\n// Assuming Mailpit is running on default port 8025\nconst MAILPIT_URL = process.env.MAILPIT_BASE_URL ?? \"http://localhost:8025\";\nconst mailpit = new MailpitClient(MAILPIT_URL);\n\nasync function runMailpitExample() {\n  // 1. Clean up any previous messages\n  await mailpit.deleteMessages();\n  console.log(\"All existing messages deleted.\");\n\n  // 2. Simulate sending an email (this would typically be done by your application under test)\n  // For demonstration, we'll use a mock 'sendMessage' if your app doesn't have an SMTP client exposed.\n  // In a real E2E test, your app would send an email that Mailpit intercepts.\n  // Example of a direct API call (not typical for E2E, but shows capability):\n  // await mailpit.sendEmail({ /* Mailpit's internal send endpoint */ });\n\n  // --- Simulate an email being sent to Mailpit (e.g., via your app) ---\n  // For a real test, you'd trigger your app to send an email here.\n  // We'll manually inject one for this quickstart's sake:\n  await mailpit.createMessage({\n    From: { Email: \"sender@example.com\", Name: \"Test Sender\" },\n    To: [{ Email: \"recipient@example.com\", Name: \"Test Recipient\" }],\n    Subject: \"Welcome to Mailpit API Client!\",\n    HTML: \"<p>Hello from Mailpit!</p>\",\n    Text: \"Hello from Mailpit!\",\n    Headers: { \"X-Test-Header\": \"Example\" }\n  });\n\n  console.log(\"Simulated email sent to Mailpit.\");\n\n  // 3. Wait for the specific message to appear in Mailpit\n  const receivedMessage = await mailpit.waitForMessage({\n    query: \"subject:\\\"Welcome to Mailpit API Client!\\\"\",\n    timeout: 10000 // Wait up to 10 seconds\n  });\n\n  console.log(\"Received message:\", receivedMessage.Subject);\n\n  // 4. Perform assertions on the received message\n  expect(receivedMessage).toBeDefined();\n  expect(receivedMessage.Subject).toEqual(\"Welcome to Mailpit API Client!\");\n  expect(receivedMessage.To[0].Address).toEqual(\"recipient@example.com\");\n  expect(receivedMessage.From.Address).toEqual(\"sender@example.com\");\n\n  // 5. Optionally, retrieve all messages and verify count\n  const allMessages = await mailpit.listMessages();\n  expect(allMessages.length).toBeGreaterThanOrEqual(1);\n  console.log(`Currently ${allMessages.length} messages in Mailpit.`);\n\n  // 6. Disconnect from WebSocket if used (for persistent connections)\n  mailpit.disconnect();\n  console.log(\"Mailpit client disconnected.\");\n}\n\nrunMailpitExample().catch(error => {\n  console.error(\"Mailpit example failed:\", error);\n  process.exit(1);\n});","lang":"typescript","description":"This quickstart demonstrates how to initialize the `MailpitClient`, clear existing emails, simulate sending an email to Mailpit, wait for a specific email to be received, and perform basic assertions on its content. It includes setup for a local Mailpit instance and uses `expect` for illustrative assertions.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}