A JavaScript promise-based wrapper for the Guerrilla Mail API
npm install guerrillamail-api[api docs]: https://docs.google.com/document/d/1Qw5KQP1j57BPTDmms5nspe-QAjNEsNg8cQHpAAycYNM/edit?hl=en
[event emitter]: https://github.com/primus/eventemitter3
sh
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.
`javascript
import GuerrillaMailApi from 'guerrillamail-api';
const GuerrillaApi = new GuerrillaMailApi();
GuerrillaApi.on('emailAddress', result => {
GuerrillaApi.getEmailList().then(result => {
// ...
});
});
`
$3
It is possible to connect to a specific inbox by setting emailUser in the config object when you instantiate the class. See config section.
`javascript
const GuerrillaApi = new GuerrillaMailApi({
emailUser: 'sampleusr'
});
`
$3
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.
`javascript
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:
`javascript
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.
$3
| 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. |
$3
`javascript
const GuerrillaApi = new GuerrillaMailApi({
emailUser: 'sampleusr'
pollInterval: 15000
});
`
Methods
$3
Methods for the API endpoints from the official [API documentation][api docs].
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][api docs].
`javascript
GuerrillaApi.getEmailAddress().then(result => {
// ...
});
`
#### setEmailUser([config])
Register a custom email user with the API.
API function: [set_email_user][api docs].
`javascript
GuerrillaApi.setEmailUser({
email_user: 'sampleusr'
}).then(result => {
// ...
});
`
#### getEmailList([config])
Get a maximum of 20 messages from the specified offset.
API function: [get_email_list][api docs].
`javascript
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][api docs].
`javascript
GuerrillaApi.getOlderList({
seq: 815
}).then(result => {
// ...
});
`
#### checkEmail([config])
API function: [check_email][api docs].
Check for new email on the server.
`javascript
GuerrillaApi.checkEmail({
seq: 456
}).then(result => {
// ...
});
`
#### fetchEmail(emailId)
API function: [fetch_email][api docs].
Get the contents of an email by ID.
`javascript
GuerrillaApi.fetchEmail(789).then(result => {
// ...
});
`
#### forgetMe()
Forget the current registered email address.
API function: [forget_me][api docs].
`javascript
GuerrillaApi.forgetMe().then(result => {
// ...
});
`
#### delEmail(emailId1 [, ...[, emailIdN]])
Delete the emails from the server by ID.
API function: [del_email][api docs].
`javascript
GuerrillaApi.delEmail(123, 456, 789).then(result => {
// ...
});
`
$3
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.
`javascript
GuerrillaApi.pollStart();
`
#### pollStop()
Stop polling for new emails.
`javascript
GuerrillaApi.pollStop();
`
#### pollPlay()
Resume polling for new emails.
`javascript
GuerrillaApi.pollPlay();
`
#### pollPause()
Pause polling for new emails.
`javascript
GuerrillaApi.pollPause();
`
#### pollDestroy()
Destroy the poller.
`javascript
GuerrillaApi.pollDestroy();
`
$3
#### destroy()
Destroy the poller and make the API forget the current email address (like you were never here!).
`javascript
GuerrillaApi.destroy();
`
$3
Guerrilla Mail API Wrapper extends [EventEmitter3][event emitter] 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)
`javascript
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.
$3
`javascript
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!
});
`
$3
| 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. |