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

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.

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.

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

This has built-in types.

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

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
}

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.

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])}`);
    }
});

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.

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.

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.