README.md

TempMail.lol JS API

This is an API for the temporary email service TempMail.lol.

If you are using a BananaCrumbs ID/Token and have not migrated, install version 3.1.0 instead of 4.x.x!

Upgrading from 3.1.0

The key difference between 3.1.0 and 4.0.0 is the fact that the constructor only accepts an API Key, and not a BananaCrumbs ID.

The custom domain method has changed as well as the createInbox method's parameters.

Upgrading from 2.0.3

The version 3.0.0+ is vastly different from the old version of the API. Please read the changes before using the new version of the API.

Version 2.0.3 still works, but does not have support for custom domains or TempMail Plus. Note that v2 support may be dropped at any time, so please upgrade your applications as soon as possible.

Installation

npm i tempmail.lol
# or, if you use yarn
yarn add tempmail.lol

This has built-in types.

Usage

First, create a TempMail object:

const tempmail = new TempMail();

//if you have a TempMail Plus/Ultra account, you can add it here:
const tempmail = new TempMail("API Key");

Types

Email:

type Email = {
    from: string,
    to: string,
    subject: string,
    body: string,
    html: string | null, //only if the email is HTML
    date: number, //date in unix millis
    ip: string, //IP address of sender
}

Inbox:

type Inbox = {
    address: string, //address of inbox
    token: string, //token to use for checkInbox
}

Create inbox

To create an inbox:

//simply, you can use the following function
tempmail.createInbox().then(inbox => {
    console.log(`Inbox: ${inbox.address} with a token of ${inbox.token}`);
});

//Or as async
const inbox: Inbox = await tempmail.createInbox();

//there are some advanced options as well

//whether or not to create a community address
tempmail.createInbox({
    community: false,
    domain: "cooldomain.com",
    prefix: "optional",
});

Note that all inboxes expire after 30 minutes since last check, with a hard expiry limit of one hour that cannot be bypassed.

TempMail Plus subscribers can extend this to TEN hours, but the 30-minute check rule still applies.

Retrieve emails

To get the emails in an inbox:

//you can also pass through the Inbox object instead of the token string
const emails = tempmail.checkInbox("<TOKEN>").then((emails) => {
    if(!emails) {
        console.log(`Inbox expired since "emails" is undefined...`);
        return;
    }
    
    console.log(`We got some emails!`);
    
    for(let i = 0; i < emails.length; i++) {
        console.log(`email ${i}: ${JSON.stringify(emails[i])}`);
    }
});

Custom Domains

Note: you will need to be a TempMail Plus/Ultra subscriber to use custom domains!

Old Custom Domains (v1)

tempmail.checkCustomDomainLegacy("example.com", "token").then(emails => {
    emails.forEach(e => {
        console.log("Email from: " + e.from + " to " + e.to);
    });
});

You can obtain a token by visiting https://tempmail.lol/custom.html

Custom domains will NOT alert you if the token is invalid.

New Custom Domains (v2)

tempmail.checkV2CustomDomain("example.com").then(emails => {
    emails.forEach(e => {
        console.log("Email from: " + e.from + " to " + e.to);
    });
});

To setup this, visit your account on https://accounts.tempmail.lol and migrate if you have not already.

Webhooks

You can set up a webhook to be called when an email is received.

tempmail.setWebhook("https://example.com/webhook").then(() => {
    console.log("Webhook set!");
});

You can also remove the webhook:

tempmail.removeWebhook().then(() => {
    console.log("Webhook removed!");
});

This feature is only available to TempMail Ultra subscribers. Any email created after setting the webhook will trigger the webhook. The email will not be returned in the checkInbox function.

Failed webhooks will not be retried unless a 429 Too Many Requests error is returned.

Webhooks will send data in a JSON format as an array of Email objects.