Guerrilla Mail API Wrapper

Common errors

• ReferenceError: GuerrillaMailApi is not defined

  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.
  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.

  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.
  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

  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.
  fix Verify that `GuerrillaApi` is correctly instantiated as `const GuerrillaApi = new GuerrillaMailApi();` before attempting to attach event listeners to it.

Warnings

• gotcha 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.
  Fix: Always attach an `on('emailAddress', ...)` listener and perform subsequent API calls or `pollStart()` inside its callback to ensure API readiness.
• gotcha 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.
  Fix: Omit `sid_token` from all method parameters. The wrapper handles it automatically and securely.
• gotcha 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.
  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.

Install

• npm install guerrillamail-api npm
• yarn add guerrillamail-api yarn
• pnpm add guerrillamail-api pnpm

Imports

• GuerrillaMailApi
  wrong:

  const GuerrillaMailApi = require('guerrillamail-api');

  correct:

  import GuerrillaMailApi from '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)
  wrong:

  const GuerrillaMailApi = require('guerrillamail-api');

  correct:

  const GuerrillaMailApi = require('guerrillamail-api').default;

  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)
  wrong:

  import { Config } from 'guerrillamail-api';

  correct:

  import type { 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.

Quickstart

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
}