Registry / communication / guerrillamail-api

guerrillamail-api

JSON →
library1.0.0jsnpmunverified

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.

npm install guerrillamail-api
INSTALL
IMPORT
SIG · GUERRILLAMAIL-API
G
guerrillamail-api
communicationjavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GuerrillaMailApi
import GuerrillaMailApi from 'guerrillamail-api';
const GuerrillaMailApi = require('guerrillamail-api');
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.
GuerrillaMailApi (CommonJS)
const GuerrillaMailApi = require('guerrillamail-api').default;
const GuerrillaMailApi = require('guerrillamail-api');
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.
Config (Type)
import type { Config } from 'guerrillamail-api';
import { Config } from 'guerrillamail-api';
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.

Demonstrates instantiation of the GuerrillaMailApi wrapper, listening for the crucial `emailAddress` event, starting and stopping email polling, and handling incoming `newEmail` events.

import GuerrillaMailApi from 'guerrillamail-api'; async function main() { // Instantiate the API wrapper, optionally setting a custom user or polling interval. const GuerrillaApi = new GuerrillaMailApi({ // Uncomment the line below to connect to a specific inbox username // emailUser: 'your_custom_username', // Set polling interval to 10 seconds (10000ms), default is 20 seconds pollInterval: 10000 }); console.log('Initializing Guerrilla Mail API wrapper...'); // Crucially, wait for the 'emailAddress' event which signals API readiness. GuerrillaApi.on('emailAddress', (result) => { console.log(`Email address registered: ${result.email_addr}`); // Start polling for new emails only after an address is assigned. GuerrillaApi.pollStart(); console.log('Started polling for new emails...'); }); // Listen for the 'newEmail' event when a message arrives. GuerrillaApi.on('newEmail', (email) => { console.log('\nNew email received!'); console.log(`From: ${email.mail_from}`); console.log(`Subject: ${email.mail_subject}`); console.log(`ID: ${email.mail_id}`); // In a production scenario, you might then fetch the full email content: // GuerrillaApi.getEmail(email.mail_id).then(fullEmail => console.log(fullEmail.mail_body)); // For this example, we'll stop polling after the first email. GuerrillaApi.pollStop(); console.log('Polling stopped after receiving an email. Re-run the script to receive another.'); }); // Implement error handling for API or wrapper issues. GuerrillaApi.on('error', (err) => { console.error('An error occurred:', err); }); // Keep the Node.js process alive to allow events to be emitted. // In a real-world application, this would be managed by a server or service lifecycle. await new Promise(resolve => setTimeout(resolve, 90000)); // Run for 90 seconds before exiting console.log('Quickstart example finished running after timeout.'); GuerrillaApi.pollStop(); // Ensure polling is stopped on exit }
Debug
Known issues
gotchaAPI 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.
fix
Always attach an `on('emailAddress', ...)` listener and perform subsequent API calls or `pollStart()` inside its callback to ensure API readiness.
affects: >=1.0.0
gotchaThe 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.
fix
Omit `sid_token` from all method parameters. The wrapper handles it automatically and securely.
affects: >=1.0.0
gotchaThe 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: GuerrillaMailApi is not defined
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.
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;`.
Error: API call failed - no email address registered.
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.
fix
Ensure all API interactions are nested within or executed after the callback of the `GuerrillaApi.on('emailAddress', ...)` event listener.
TypeError: GuerrillaApi.on is not a function
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.
fix
Verify that `GuerrillaApi` is correctly instantiated as `const GuerrillaApi = new GuerrillaMailApi();` before attempting to attach event listeners to it.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
axiosrequiredHandles promise-based HTTP requests to the Guerrilla Mail API.
eventemitter3requiredProvides an event-driven interface for email address registration and new email reception.
setinterval-plusrequiredManages interval polling for new emails with control methods like start/stop/pause/play.
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
guerrillamail-api — npm install guerrillamail-api · libregistry