guerrillamail-api

Guerrilla Mail API Wrapper

A Promise-based Javascript wrapper for the Guerrillamail API.

Features

• Interval polling with built-in start, stop, play, pause methods, using setinterval-plus
• Promise-based, using Axios
• Event emitter, using EventEmitter3

Installation

npm install guerrillamail-api

Usage

Important: Once you instantiate the class, you must wait for the API to register a random email address. This is still the case, even if you are using a custom email address.

The class will emit the emailAddress event when an email address has been successfully registered with the API. Read more about the available event methods.

import GuerrillaMailApi from 'guerrillamail-api';

const GuerrillaApi = new GuerrillaMailApi();

GuerrillaApi.on('emailAddress', result => {
    GuerrillaApi.getEmailList().then(result => {
        // ...
    });
});

Custom email address

It is possible to connect to a specific inbox by setting emailUser in the config object when you instantiate the class. See config section.

const GuerrillaApi = new GuerrillaMailApi({
    emailUser: 'sampleusr'
});

Polling

Use pollStart() to start polling the inbox for new emails.

As with all methods which interact with the API, you must call the pollStart() method after the API has registered an email address.

GuerrillaApi.on('emailAddress', result => {
    // Begin polling for new emails after the email address has been registered
    GuerrillaApi.pollStart();
});

Wait for the poller to emit the newEmail event:

GuerrillaApi.on('newEmail', result => {
    // You got mail!
});

Tips

• Control the frequency of polling by setting pollInterval when you instantiate the class.
• It is possible to play, pause and stop polling for emails. See polling methods.

Config

Pass config options when instantiating the wrapper.

Config reference table

Config Property	Type	Default	Description
emailUser	Boolean|String	false	Connect to a specific inbox, otherwise the API will assign you a random inbox.
pollInterval	Number	20000	How often (in milliseconds) to poll for new emails.

Example

const GuerrillaApi = new GuerrillaMailApi({
    emailUser: 'sampleusr'
    pollInterval: 15000
});

Methods

Guerrilla API Methods

Methods for the API endpoints from the official API documentation.

Important: Do not pass an sid_token to any methods. Guerrilla Mail API Wrapper will take care of this internally.

getEmailAddress([config])

Register a new random email address with the API.

API function: get_email_address.

GuerrillaApi.getEmailAddress().then(result => {
    // ...
});

setEmailUser([config])

Register a custom email user with the API.

API function: set_email_user.

GuerrillaApi.setEmailUser({
    email_user: 'sampleusr'
}).then(result => {
    // ...
});

getEmailList([config])

Get a maximum of 20 messages from the specified offset.

API function: get_email_list.

GuerrillaApi.getEmailList({
    offset: 0
}).then(result => {
    // ...
});

getOlderList([config])

Get emails that are older (lower ID) than the given email ID (where seq is the ID).

API function: get_older_list.

GuerrillaApi.getOlderList({
    seq: 815
}).then(result => {
    // ...
});

checkEmail([config])

API function: check_email.

Check for new email on the server.

GuerrillaApi.checkEmail({
    seq: 456
}).then(result => {
    // ...
});

fetchEmail(emailId)

API function: fetch_email.

Get the contents of an email by ID.

GuerrillaApi.fetchEmail(789).then(result => {
    // ...
});

forgetMe()

Forget the current registered email address.

API function: forget_me.

GuerrillaApi.forgetMe().then(result => {
    // ...
});

delEmail(emailId1 [, ...[, emailIdN]])

Delete the emails from the server by ID.

API function: del_email.

GuerrillaApi.delEmail(123, 456, 789).then(result => {
    // ...
});

Polling Methods

Methods for controlling the polling interval.

pollStart()

Start polling for new emails every x milliseconds, as defined by pollInterval.

See event examples of how to react when new emails are received.

GuerrillaApi.pollStart();

pollStop()

Stop polling for new emails.

GuerrillaApi.pollStop();

pollPlay()

Resume polling for new emails.

GuerrillaApi.pollPlay();

pollPause()

Pause polling for new emails.

GuerrillaApi.pollPause();

pollDestroy()

Destroy the poller.

GuerrillaApi.pollDestroy();

Misc Methods

destroy()

Destroy the poller and make the API forget the current email address (like you were never here!).

GuerrillaApi.destroy();

Event Methods

Guerrilla Mail API Wrapper extends EventEmitter3 which means you have access to an .on() method. This is useful for listening for events, such as when a new email is received, or when the email address has been assigned by the API.

See full list of emitted events in the event reference table.

on(eventString, data)

GuerrillaApi.on('newEmail', newEmails => {
    // Do stuff with the new emails
});

Events

Event strings are emitted in certain situations, which can be listened for using the .on() method.

Important: The key event to listen for is emailAddress. This means the API has registered the inbox and is ready.

Event examples:

GuerrillaApi.on('emailAddress', emailAddressDetails => {
    GuerrillaApi.pollStart(); // Start polling for new emails
});

GuerrillaApi.on('emailAddressError', error => {
    // Email address wasn't assigned
});

GuerrillaApi.on('newEmail', newEmails => {
    // You got mail!
});

Event reference table

Event string	Emission reason
emailAddress	An email address has been assigned by the API.
emailAddressError	An email user or address request errors.
newEmail	New email has been received.
pollRequestStart	A poll request is attempted.
pollRequestComplete	A poll request has been completed.
pollRequestError	A poll request has an error.

Todo

• Write tests
• Add option for callbacks instead of promises

Changelog

[1.2.2] - 2019-02-14

Fixed

• README code block language.