A Promise-based Javascript wrapper for the Guerrillamail API.

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

npm install guerrillamail-api

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 => {
        // ...
    });
});

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'
});

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!
});

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

Pass config options when instantiating the wrapper.

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

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.

Register a new random email address with the API.

API function: get_email_address.

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

Register a custom email user with the API.

API function: set_email_user.

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

Get a maximum of 20 messages from the specified offset.

API function: get_email_list.

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

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 => {
    // ...
});

API function: check_email.

Check for new email on the server.

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

API function: fetch_email.

Get the contents of an email by ID.

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

Forget the current registered email address.

API function: forget_me.

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

Delete the emails from the server by ID.

API function: del_email.

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

Methods for controlling the polling interval.

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();

Stop polling for new emails.

GuerrillaApi.pollStop();

Resume polling for new emails.

GuerrillaApi.pollPlay();

Pause polling for new emails.

GuerrillaApi.pollPause();

Destroy the poller.

GuerrillaApi.pollDestroy();

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

GuerrillaApi.destroy();

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.

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

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.

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!
});

• Write tests
• Add option for callbacks instead of promises