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
muslnode 18–226 runs
build_error
glibcnode 18–226 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
}
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.
fixFor 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.
fixEnsure 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.
fixVerify that `GuerrillaApi` is correctly instantiated as `const GuerrillaApi = new GuerrillaMailApi();` before attempting to attach event listeners to it.
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.