📬 DX Mail

Fast temporary email client with realtime inbox updates.

DX Mail lets you create temporary email inboxes, listen for incoming messages instantly, and integrate them into bots, dashboards, automation tools, or Node.js apps.

No server URL setup needed. Just install, authenticate, create an inbox, and listen for incoming emails. Tiny client, realtime inbox, big mailbox energy. ⚡

✨ Features

• 🚀 Create random temporary email addresses
• 🏷️ Create custom email addresses
• ⚡ Realtime inbox updates using WebSocket
• 📥 Read message history
• 🌐 Supports plain text and HTML emails
• 🤖 Works great with Telegram and WhatsApp bots
• 🧩 Simple and friendly API
• 🔑 API key authentication
• 📦 Lightweight Node.js client

📦 Installation

npm install dx-mail

🚀 Quick Start

const dxMail = require("dx-mail");

const app = dxMail();

app.auth("dxm_your_api_key");

async function main() {
  const res = await app.createMail();

  console.log("Your email address:");
  console.log(res.inbox.address);
}

main().catch(console.error);

Example output:

[email protected]

🔐 Authentication

Authenticate using your DX Mail API key.

const dxMail = require("dx-mail");

const app = dxMail();

app.auth("dxm_your_api_key");

You can also pass the token directly.

const dxMail = require("dx-mail");

const app = dxMail("dxm_your_api_key");

📮 Create a Random Email

const res = await app.createMail();

console.log(res.inbox.address);

Example:

[email protected]

🏷️ Create a Custom Email

const res = await app.createMail("test1");

console.log(res.inbox.address);

Example:

[email protected]

🧵 Callback Style

DX Mail supports both Promise and callback styles.

app.createMail("test1", (res) => {
  console.log(res.inbox.address);
});

app.listMail((res) => {
  console.log(res.inboxes);
});

📚 List All Emails

Get all inboxes owned by your API key.

const res = await app.listMail();

console.log(res.inboxes);

Example response:

{
  ok: true,
  count: 2,
  inboxes: [
    {
      id: "667f...",
      name: "test1",
      address: "[email protected]",
      domain: "yourdomain.com",
      expiresAt: "2026-06-28T10:00:00.000Z",
      createdAt: "2026-06-27T10:00:00.000Z"
    }
  ]
}

📥 Read Messages

const res = await app.getMail("test1");

console.log(res.messages);

You can also use:

const res = await app.getMessages("test1");

console.log(res.messages);

⚡ Watch an Inbox Realtime

Listen for incoming emails instantly.

app.watchMail("test1", (event) => {
  console.log("New email received!");
  console.log("From:", event.message.from);
  console.log("Subject:", event.message.subject);
  console.log("Text:", event.message.text);
});

When an email arrives, you will receive an event like this:

{
  type: "mail.received",
  inbox: {
    id: "667f...",
    name: "test1",
    address: "[email protected]"
  },
  message: {
    id: "6680...",
    to: "[email protected]",
    from: "[email protected]",
    subject: "Welcome",
    text: "Hello from DX Mail!",
    html: "<p>Hello from DX Mail!</p>",
    attachments: [],
    receivedAt: "2026-06-27T14:00:00.000Z"
  }
}

🛑 Stop Watching

watchMail() returns an unsubscribe function.

const stop = app.watchMail("test1", (event) => {
  console.log(event.message.subject);
});

stop();

🌐 Watch All Inboxes

Listen to all inboxes owned by your API key.

const stop = app.watchAll((event) => {
  console.log("Inbox:", event.inbox.address);
  console.log("Subject:", event.message.subject);
});

stop();

⏳ Wait for One Email

Useful for OTP, verification links, or test automation.

const event = await app.waitMail("test1");

console.log(event.message.subject);
console.log(event.message.text);

With timeout:

const event = await app.waitMail("test1", {
  timeoutMs: 30000
});

🌍 HTML Email Support

Many platforms send HTML emails. DX Mail supports both text and HTML bodies.

app.watchMail("test1", (event) => {
  if (event.message.html) {
    console.log("HTML email received:");
    console.log(event.message.html);
  } else {
    console.log(event.message.text);
  }
});

For web inboxes, sanitize HTML before rendering it to users.

🤖 Telegram Bot Example

const dxMail = require("dx-mail");

const app = dxMail();

app.auth("dxm_your_api_key");

async function createUserMail(ctx) {
  const res = await app.createMail();

  await ctx.reply(`Your temporary email:\n${res.inbox.address}`);

  app.watchMail(res.inbox.name, async (event) => {
    await ctx.reply(
      `📩 New email!\n\nFrom: ${event.message.from}\nSubject: ${event.message.subject}\n\n${event.message.text}`
    );
  });
}

💬 WhatsApp Bot Example

const dxMail = require("dx-mail");

const app = dxMail();

app.auth("dxm_your_api_key");

async function createWhatsAppMail(sock, jid) {
  const res = await app.createMail();

  await sock.sendMessage(jid, {
    text: `Your temporary email:\n${res.inbox.address}`
  });

  app.watchMail(res.inbox.name, async (event) => {
    await sock.sendMessage(jid, {
      text:
        `📩 New email!\n\n` +
        `From: ${event.message.from}\n` +
        `Subject: ${event.message.subject}\n\n` +
        `${event.message.text}`
    });
  });
}

🖥️ Web Inbox Example

const dxMail = require("dx-mail");

const app = dxMail();

app.auth("dxm_your_api_key");

app.watchMail("test1", (event) => {
  renderMessage(event.message);
});

function renderMessage(message) {
  console.log(message.subject);
  console.log(message.text);
}

🧠 API Reference

dxMail()

Create a new DX Mail client.

const app = dxMail();

dxMail(token)

Create a new client and set the API key immediately.

const app = dxMail("dxm_your_api_key");

app.auth(token)

Set or update the API key.

app.auth("dxm_your_api_key");

app.createMail(name?)

Create a temporary inbox.

await app.createMail();
await app.createMail("customname");

app.listMail()

List all inboxes owned by the API key.

await app.listMail();

app.getMail(name)

Get messages from an inbox.

await app.getMail("test1");

app.getMessages(name)

Alias for getMail().

await app.getMessages("test1");

app.watchMail(name, callback)

Watch one inbox in realtime.

const stop = app.watchMail("test1", callback);

app.watchAll(callback)

Watch all inboxes in realtime.

const stop = app.watchAll(callback);

app.waitMail(name, options?)

Wait until one email arrives.

const event = await app.waitMail("test1", {
  timeoutMs: 60000
});

app.close()

Close the WebSocket connection.

app.close();

📦 Response Shapes

Inbox

{
  id: "667f...",
  name: "test1",
  address: "[email protected]",
  domain: "yourdomain.com",
  expiresAt: "2026-06-28T10:00:00.000Z",
  createdAt: "2026-06-27T10:00:00.000Z"
}

Message

{
  id: "6680...",
  inboxId: "667f...",
  to: "[email protected]",
  from: "[email protected]",
  subject: "Welcome",
  text: "Hello!",
  html: "<p>Hello!</p>",
  attachments: [],
  receivedAt: "2026-06-27T14:00:00.000Z",
  createdAt: "2026-06-27T14:00:01.000Z"
}

⚙️ Environment Variable

You can also set your token using an environment variable.

DX_MAIL_TOKEN=dxm_your_api_key

Then:

const dxMail = require("dx-mail");

const app = dxMail();

const res = await app.createMail();
console.log(res.inbox.address);

🧪 Full Example

const dxMail = require("dx-mail");

const app = dxMail();

app.auth("dxm_your_api_key");

async function main() {
  const created = await app.createMail("demo");

  console.log("Email created:", created.inbox.address);

  app.watchMail("demo", (event) => {
    console.log("\n📩 New email!");
    console.log("From:", event.message.from);
    console.log("Subject:", event.message.subject);
    console.log("Text:", event.message.text);
    console.log("HTML:", event.message.html ? "yes" : "no");
  });

  console.log("Waiting for emails...");
}

main().catch(console.error);

🔒 Security Notes

• Do not expose your API key in public frontend apps.
• Use server-side bots or backend services when possible.
• Sanitize HTML before rendering emails in a browser.
• Rotate API keys if they are leaked.
• Do not commit .env files to GitHub.

🧹 Cleanup

Close the connection when your app shuts down.

process.on("SIGINT", () => {
  app.close();
  process.exit(0);
});

🛠️ Built For

• Temporary email systems
• OTP listeners
• Verification email capture
• Telegram bots
• WhatsApp bots
• Web inbox dashboards
• Automation scripts
• Developer testing tools

📄 License

MIT

Made for fast inbox experiments, bot builders, and people who enjoy turning email into realtime little lightning bolts. ⚡