{"id":16369,"library":"guerrillamail-api","title":"Guerrilla Mail API Wrapper","description":"A JavaScript promise-based wrapper for the Guerrilla Mail API, providing a convenient interface for programmatic interaction with temporary email addresses. This package, currently at stable version 1.2.2, simplifies common tasks such as registering new email addresses, fetching incoming mail, and managing inboxes. While there isn't an explicit release cadence stated, the project demonstrates active maintenance, as evidenced by its recent version tag and feature set. Key differentiators include its promise-based architecture leveraging Axios for robust HTTP requests, an integrated interval poller powered by `setinterval-plus` that offers methods like `start`, `stop`, `play`, and `pause` for managing email reception, and comprehensive event-driven communication via `EventEmitter3`. This event system emits crucial signals such as `emailAddress` upon successful address registration and `newEmail` when new messages arrive, streamlining asynchronous workflows. Furthermore, the wrapper abstracts away the internal handling of `sid_token`s, simplifying API calls for developers.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/Dobby89/guerrillamail-api","tags":["javascript","guerrillamail","guerrilla","mail","email","api","wrapper"],"install":[{"cmd":"npm install guerrillamail-api","lang":"bash","label":"npm"},{"cmd":"yarn add guerrillamail-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add guerrillamail-api","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Handles promise-based HTTP requests to the Guerrilla Mail API.","package":"axios"},{"reason":"Provides an event-driven interface for email address registration and new email reception.","package":"eventemitter3"},{"reason":"Manages interval polling for new emails with control methods like start/stop/pause/play.","package":"setinterval-plus"}],"imports":[{"note":"The primary way to import the main class in modern JavaScript/TypeScript projects using ES Modules. Direct CommonJS `require` may return an object with a `.default` property if transpiled.","wrong":"const GuerrillaMailApi = require('guerrillamail-api');","symbol":"GuerrillaMailApi","correct":"import GuerrillaMailApi from 'guerrillamail-api';"},{"note":"For CommonJS environments where the package is transpiled from ESM. Attempting to access `GuerrillaMailApi` directly via `require('guerrillamail-api')` without `.default` will likely result in an undefined class.","wrong":"const GuerrillaMailApi = require('guerrillamail-api');","symbol":"GuerrillaMailApi (CommonJS)","correct":"const GuerrillaMailApi = require('guerrillamail-api').default;"},{"note":"If using TypeScript, the `Config` interface (for options like `emailUser`, `pollInterval`) can be imported as a type. Using `import type` is preferred for clarity and to ensure it's removed during transpilation.","wrong":"import { Config } from 'guerrillamail-api';","symbol":"Config (Type)","correct":"import type { Config } from 'guerrillamail-api';"}],"quickstart":{"code":"import GuerrillaMailApi from 'guerrillamail-api';\n\nasync function main() {\n  // Instantiate the API wrapper, optionally setting a custom user or polling interval.\n  const GuerrillaApi = new GuerrillaMailApi({\n    // Uncomment the line below to connect to a specific inbox username\n    // emailUser: 'your_custom_username',\n    // Set polling interval to 10 seconds (10000ms), default is 20 seconds\n    pollInterval: 10000\n  });\n\n  console.log('Initializing Guerrilla Mail API wrapper...');\n\n  // Crucially, wait for the 'emailAddress' event which signals API readiness.\n  GuerrillaApi.on('emailAddress', (result) => {\n    console.log(`Email address registered: ${result.email_addr}`);\n    // Start polling for new emails only after an address is assigned.\n    GuerrillaApi.pollStart();\n    console.log('Started polling for new emails...');\n  });\n\n  // Listen for the 'newEmail' event when a message arrives.\n  GuerrillaApi.on('newEmail', (email) => {\n    console.log('\\nNew email received!');\n    console.log(`From: ${email.mail_from}`);\n    console.log(`Subject: ${email.mail_subject}`);\n    console.log(`ID: ${email.mail_id}`);\n    // In a production scenario, you might then fetch the full email content:\n    // GuerrillaApi.getEmail(email.mail_id).then(fullEmail => console.log(fullEmail.mail_body));\n    \n    // For this example, we'll stop polling after the first email.\n    GuerrillaApi.pollStop(); \n    console.log('Polling stopped after receiving an email. Re-run the script to receive another.');\n  });\n\n  // Implement error handling for API or wrapper issues.\n  GuerrillaApi.on('error', (err) => {\n    console.error('An error occurred:', err);\n  });\n\n  // Keep the Node.js process alive to allow events to be emitted.\n  // In a real-world application, this would be managed by a server or service lifecycle.\n  await new Promise(resolve => setTimeout(resolve, 90000)); // Run for 90 seconds before exiting\n  console.log('Quickstart example finished running after timeout.');\n  GuerrillaApi.pollStop(); // Ensure polling is stopped on exit\n}","lang":"javascript","description":"Demonstrates instantiation of the GuerrillaMailApi wrapper, listening for the crucial `emailAddress` event, starting and stopping email polling, and handling incoming `newEmail` events."},"warnings":[{"fix":"Always attach an `on('emailAddress', ...)` listener and perform subsequent API calls or `pollStart()` inside its callback to ensure API readiness.","message":"API methods and polling cannot be initiated immediately after class instantiation. You must wait for the `emailAddress` event to be emitted, indicating that an email address has been successfully registered with the Guerrilla Mail API. This applies even when using a custom email user.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Omit `sid_token` from all method parameters. The wrapper handles it automatically and securely.","message":"The wrapper internally manages the `sid_token` required for API authentication. Developers should not manually pass `sid_token` to any method calls, as this can lead to unexpected behavior, authentication conflicts, or errors with the wrapper's internal state management.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure the `pollInterval` option during instantiation (`new GuerrillaMailApi({ pollInterval: 30000 })`) to a reasonable value, preferably 10 seconds or more, to respect API limits and maintain good performance.","message":"The default polling interval is 20 seconds. Frequent or excessively rapid polling (e.g., less than 10 seconds) can strain the Guerrilla Mail API and may lead to temporary rate limiting or even IP blocking. Excessive requests can also unnecessarily consume system resources.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import GuerrillaMailApi from 'guerrillamail-api';`. For CommonJS environments, ensure you access the `.default` property: `const GuerrillaMailApi = require('guerrillamail-api').default;`.","cause":"Attempting to use `require()` for importing the ES module default export, or failing to access the `.default` property if using CommonJS `require` on a transpiled ES module.","error":"ReferenceError: GuerrillaMailApi is not defined"},{"fix":"Ensure all API interactions are nested within or executed after the callback of the `GuerrillaApi.on('emailAddress', ...)` event listener.","cause":"An API method (e.g., `getEmailList`, `pollStart()`, `setEmailUser()`) was called before the `emailAddress` event was emitted, indicating the wrapper has not yet successfully established an email session with the Guerrilla Mail API.","error":"Error: API call failed - no email address registered."},{"fix":"Verify that `GuerrillaApi` is correctly instantiated as `const GuerrillaApi = new GuerrillaMailApi();` before attempting to attach event listeners to it.","cause":"The `GuerrillaMailApi` class was not properly instantiated using the `new` keyword, or the event listener was attempted on an object that is not an `EventEmitter` instance.","error":"TypeError: GuerrillaApi.on is not a function"}],"ecosystem":"npm"}