tempninja

Generate disposable email addresses and read their inboxes — powered by tempmail.ninja.

Installation

npm install tempninja

Usage

const { createEmail, checkInbox } = require("tempninja");

// Generate a new temporary email
const { email, token, expiresAt } = await createEmail();
console.log(email); // [email protected]

// Check inbox using the email address
const { count, messages } = await checkInbox(email);

// Or check inbox using the token
const { count, messages } = await checkInbox(token);

API

createEmail()

Generates a new temporary email address.

Returns: Promise<Object>

| Field | Type | Description | |---|---|---| | email | string | The generated email address | | token | string | JWT token — use this to check the inbox | | expiresAt | string | ISO datetime when the email expires (~1 hour) | | createdAt | string | ISO datetime when the email was created |

Example:

const result = await createEmail();

console.log(result);
// {
//   email: "[email protected]",
//   token: "eyJhbGciOiJIUzI1NiJ9...",
//   expiresAt: "2024-01-01T02:00:00.000Z",
//   createdAt: "2024-01-01T01:00:00.000Z"
// }

checkInbox(inbox)

Fetches all messages in the inbox for a given email address or token.

Parameters:

| Param | Type | Description | |---|---|---| | inbox | string | Email address or JWT token returned by createEmail() |

Returns: Promise<Object>

| Field | Type | Description | |---|---|---| | email | string | The resolved email address | | count | number | Number of messages in the inbox | | messages | Array | List of message objects (see below) |

Message object:

| Field | Type | Description | |---|---|---| | id | string | Unique message ID | | date | string | Date the message was received | | subject | string | Email subject line | | from | string | Sender address | | to | string | Recipient address | | body | string | Plain text version of the email body | | bodyHtml | string | Full HTML version of the email body | | attachments | Array | List of attachments (if any) |

Example:

const { email, count, messages } = await checkInbox("[email protected]");

console.log(count); // 1
console.log(messages[0].subject); // "Your verification code"
console.log(messages[0].body);    // "Your code is 123456"

Full Example

const { createEmail, checkInbox } = require("tempninja");

async function main() {
  const { email, token } = await createEmail();
  console.log("Use this email:", email);

  // ... trigger an email to be sent to that address ...

  // Poll inbox until a message arrives
  let messages = [];
  while (messages.length === 0) {
    await new Promise(r => setTimeout(r, 3000));
    const result = await checkInbox(token);
    messages = result.messages;
  }

  console.log("Subject:", messages[0].subject);
  console.log("Body:", messages[0].body);
}

main();

Notes

• Emails expire approximately 1 hour after creation.
• The token returned by createEmail() is equivalent to the email address for inbox checks — use whichever is convenient.
• Each function call opens a fresh WebSocket connection and closes it when done.
• First call may take 3–6 seconds due to the WebSocket handshake.

License

MIT