VenumzMail Docs

VenumzMail's Javascript/Typescript Node.js SDK and CLI tool. Create inboxes, read messages, extract OTPs, stream live mail, manage custom domains etc.. Everything which is possible through our API!

Contents

• Install
• Auth
• SDK
  • VMail
  • createInbox
  • createInboxes
  • listInboxes
  • reactivate
  • deleteInboxes
  • getMessages
  • getMessage
  • waitForMessage
  • waitForOtp
  • stream
  • emailLogin
  • emailStream
  • downloadAttachment
  • me
  • Domains
  • Subdomains
  • Objects
  • Errors
• CLI

Install

npm install venumzmail

Auth

Pass your API key when creating a VMail instance. Keys always start with vz-.

const { VMail } = require("venumzmail");
// or
// import { VMail } from "venumzmail";

const m = new VMail("vz-yourkey");

No key = guest mode — tracked by IP, limited to public inboxes and basic creation. Most features require a key.

const g = new VMail(); // guest

SDK

VMail

new VMail((apiKey = null), (timeout = 15));

| param | type | default | description | | --------- | ------ | ------- | ----------------------------------- | | apiKey | string | null | your API key, must start with vz- | | timeout | number | 15 | request timeout in seconds |

const m = new VMail("vz-yourkey");
const m = new VMail("vz-yourkey", 30);
const m = new VMail(); // guest mode

Note: Both camelCase and snake_case styles are supported on the client (e.g. createInbox and create_inbox work identically).

createInbox

Create a single inbox.

await m.createInbox(
  (username = null),
  (domain = null),
  (type = "private"),
  (usernameLength = null),
);

| param | type | default | description | | ---------------- | ------ | ----------- | ----------------------------------------- | | username | string | null | custom username, random if omitted | | domain | string | null | domain to use, random built-in if omitted | | type | string | "private" | "private" or "public" | | usernameLength | number | null | length of random username (3–25) |

Returns an Inbox object.

const box = await m.createInbox();
const box = await m.createInbox("myinbox", "bomboclato.store");
const box = await m.createInbox(undefined, undefined, "public");
const box = await m.createInbox(undefined, undefined, undefined, 15);

console.log(box.email);       // [email protected]
console.log(box.expires_at);  // 2026-06-20T10:30:00Z
console.log(box.active);      # true

createInboxes

Create multiple inboxes in one call (up to 50).

await m.createInboxes(
  (count = 1),
  (usernames = null),
  (domain = null),
  (type = "private"),
);

| param | type | default | description | | ----------- | -------- | ----------- | ---------------------------------------------- | | count | number | 1 | how many inboxes to create | | usernames | string[] | null | custom usernames, must match count if passed | | domain | string | null | domain for all inboxes | | type | string | "private" | "private" or "public" |

Returns a list of Inbox objects.

const boxes = await m.createInboxes(5);

const boxes = await m.createInboxes(
  3,
  ["alice", "bob", "carol"],
  "bomboclato.store",
);

for (const box of boxes) {
  console.log(box.email);
}

listInboxes

List all inboxes on your account.

await m.listInboxes();

Returns a list of Inbox objects.

const boxes = await m.listInboxes();
for (const box of boxes) {
  console.log(box.email, box.active);
}

reactivate

Extend an inbox's expiry.

await m.reactivate(email);

Returns a object with the new expires_at.

const res = await m.reactivate("[email protected]");
console.log(res.expires_at);

deleteInboxes

Delete inboxes by email list or wipe the oldest N.

await m.deleteInboxes((emails = null), (count = null));

Pass one of — not both.

await m.deleteInboxes(["[email protected]", "[email protected]"]);
await m.deleteInboxes(undefined, 3); // deletes 3 oldest

getMessages

Get all messages in an inbox.

await m.getMessages(email);

Returns a list of Message objects (empty list if no mail yet).

const msgs = await m.getMessages("[email protected]");
for (const msg of msgs) {
  console.log(msg.sender, msg.subject, msg.otp);
}

getMessage

Get a single message by its ID.

await m.getMessage(messageId);

Returns a Message object. Raises NotFoundError if ID doesn't exist.

const msg = await m.getMessage("48f732e8-c2e0-477e-9073-03a33d89f2cc");
console.log(msg.body);
console.log(msg.body_html);

waitForMessage

Poll an inbox until a message arrives or timeout is hit.

await m.waitForMessage(
  email,
  (timeout = 60),
  (pollEvery = 2),
  (subjectContains = null),
);

| param | type | default | description | | ----------------- | ------ | -------- | -------------------------------------------- | | email | string | required | inbox to watch | | timeout | number | 60 | seconds before giving up | | pollEvery | number | 2 | seconds between checks | | subjectContains | string | null | only match messages with this in the subject |

Returns a Message object or null if timed out.

const msg = await m.waitForMessage("[email protected]");

const msg = await m.waitForMessage(
  "[email protected]",
  120,
  3,
  "welcome",
);

if (msg) {
  console.log(msg.sender, msg.subject);
} else {
  console.log("timed out");
}

waitForOtp

Poll an inbox until a message with an OTP is found.

await m.waitForOtp(email, (timeout = 60), (pollEvery = 2));

Returns the OTP as a plain string, or null if timed out.

const otp = await m.waitForOtp("[email protected]");
console.log(otp); // "482910"

stream

Live stream incoming messages for one of your own inboxes via SSE.

await m.stream(email);

Returns an async generator that yields Message objects as they arrive.

for await (const msg of m.stream("[email protected]")) {
  console.log(msg.sender, msg.subject, msg.otp);
}

emailLogin

Read a public inbox without an API key.

await new VMail().emailLogin(email);

Returns a object with inbox info + a messages key containing a list of Message objects.

const g = new VMail();
const data = await g.emailLogin("[email protected]");

console.log(data.email);
console.log(data.active);
console.log(data.expires_at);
for (const msg of data.messages) {
  console.log(msg.sender, msg.subject);
}

emailStream

Live stream a public inbox without an API key.

await new VMail().emailStream(email);

Returns an async generator that yields Message objects as they arrive.

const g = new VMail();
for await (const msg of g.emailStream("[email protected]")) {
  console.log(msg.sender, msg.subject);
}

downloadAttachment

Download an attachment by its ID.

await m.downloadAttachment(attachmentId, (saveTo = null), (isPublic = false));

| param | type | default | description | | -------------- | ------- | -------- | -------------------------------------------- | | attachmentId | string | required | ID from message.attachments | | saveTo | string | null | file path to save to, returns path if given | | isPublic | boolean | false | set true for attachments from public inboxes |

Returns the save path if saveTo is given, otherwise raw Buffer.

// save to file
await m.downloadAttachment("uuid-here", "./invoice.pdf");

// get buffer
const data = await m.downloadAttachment("uuid-here");

// public inbox attachment, no key needed
const g = new VMail();
await g.downloadAttachment("uuid-here", "file.pdf", true);

me

Get account info for the current API key.

await m.me();

Returns a raw object.

const info = await m.me();
console.log(info);
// {"email": "[email protected]", "plan": "shadow", "inboxes_used": 3, ...}

Domains

Manage custom domains on your account. Requires a paid plan.

await m.addDomain(domain); // register a domain
await m.listDomains(); // list all registered domains
await m.removeDomain(domain); // remove a domain

Before addDomain works, you need to add an MX record on your domain:

Type: MX
Host: @
Value: mail.venumzmail.xyz
Priority: 10

await m.addDomain("example.com");

const domains = await m.listDomains();
for (const d of domains) {
  console.log(d.domain, d.status);
}

await m.removeDomain("example.com");

Subdomains

Create subdomains on venumzmail's built-in base domains. Requires a registered account.

await m.addSubdomain(label, baseDomain); // e.g. "team", "venumzmail.lol" → team.venumzmail.lol
await m.listSubdomains();
await m.removeSubdomain(subdomain); // full subdomain string e.g. "team.venumzmail.lol"

await m.addSubdomain("team", "venumzmail.lol");

console.log(await m.listSubdomains());

// create an inbox on your subdomain
const box = await m.createInbox(undefined, "team.venumzmail.lol");
console.log(box.email); // [email protected]

await m.removeSubdomain("team.venumzmail.lol");

Objects

Inbox

| attribute | type | description | | ---------------------------- | ------- | --------------------------- | | .email | string | full email address | | .domain | string | domain part | | .id | string | unique inbox ID | | .active | boolean | whether inbox is active | | .encrypted | boolean | whether inbox is encrypted | | .expires_at / .expiresAt | string | ISO 8601 expiry timestamp | | .created_at / .createdAt | string | ISO 8601 creation timestamp |

Message

| attribute | type | description | | ------------------------------ | -------------- | --------------------------------- | | .id | string | unique message ID | | .sender | string | sender email | | .subject | string | subject line | | .body | string | plain text body | | .body_html / .bodyHtml | string | HTML body | | .otp | string or null | extracted OTP if found, else null | | .received_at / .receivedAt | string | ISO 8601 timestamp | | .attachments | Attachment[] | list of attachment objects |

Attachment

| attribute | type | description | | -------------------------------- | ------ | --------------------------------------------- | | .id | string | attachment ID (use with downloadAttachment) | | .filename | string | original filename | | .size | number | size in bytes | | .content_type / .contentType | string | MIME type e.g. application/pdf |

Errors

All errors extend VenumzError and print a colored error: + fix: hint automatically.

| error | when | | ---------------- | -------------------------------------------------- | | AuthError | bad/missing key, guest trying a restricted feature | | RateLimitError | too many requests for your plan | | NotFoundError | inbox, message, or attachment doesn't exist | | ApiError | any other 4xx/5xx — has .status_code |

const {
  NotFoundError,
  RateLimitError,
  AuthError,
  ApiError,
} = require("venumzmail");

try {
  const msg = await m.getMessage("bad-id");
} catch (e) {
  if (e instanceof NotFoundError) {
    console.log(e); // prints error + fix hint
  } else if (e instanceof RateLimitError) {
    // retry after wait
  } else if (e instanceof AuthError) {
    console.log("check your key");
  } else if (e instanceof ApiError) {
    console.log(e.status_code);
  }
}

CLI

Auth

# inline
vmail -k vz-yourkey <command>

# or set once
export x-api-key=vz-yourkey
vmail <command>

No key = guest mode.

Commands

help

Show all commands.

vmail help

me

Get account info.

vmail me

create

Create one or more inboxes.

vmail create                                              # random
vmail create -u myinbox -d bomboclato.store              # custom username + domain
vmail create -t public                                   # public inbox
vmail create -l 15                                       # random 15-char username
vmail create -n 5                                        # bulk, 5 random inboxes
vmail create -n 3 --usernames alice bob carol -d bomboclato.store

| flag | short | description | | ------------- | ----- | ------------------------------- | | --username | -u | custom username | | --domain | -d | domain | | --type | -t | private (default) or public | | --length | -l | random username length | | --count | -n | number of inboxes | | --usernames | | space-separated names for bulk |

list

List all inboxes.

vmail list

reactivate

Extend inbox expiry.

vmail reactivate [email protected]

delete

Delete inboxes.

vmail delete --emails [email protected] [email protected]
vmail delete --count 3   # deletes 3 oldest

messages

List messages in an inbox.

vmail messages [email protected]
vmail messages [email protected] --body   # include body preview

Output per message:

[id]  [email protected]  subject='Hello'  otp=null  at=2026-06-20T09:00:00Z

message

Get a single message in full.

vmail message <message-id>

wait

Block until a message arrives.

vmail wait [email protected]
vmail wait [email protected] --otp                        # return just the OTP
vmail wait [email protected] --subject "verify"           # filter by subject
vmail wait [email protected] --timeout 120 --poll 5

| flag | default | description | | ----------- | ------- | --------------------------------------------------- | | --otp | off | extract and print just the OTP | | --subject | none | only match messages containing this text in subject | | --timeout | 60 | seconds before giving up | | --poll | 2 | seconds between checks |

stream

Live stream messages as they arrive. Ctrl+C to stop.

vmail stream [email protected]
vmail stream [email protected] --public   # public inbox, no key needed

download

Download an attachment.

vmail download <attachment-id> -o ./invoice.pdf
vmail download <attachment-id>                  # prints byte count, doesn't save
vmail download <attachment-id> --public         # public inbox attachment

login

Read a public inbox without a key.

vmail login [email protected]

domains

Manage custom domains (paid plan only).

vmail domains                        # list
vmail domains --add example.com
vmail domains --remove example.com

subdomains

Manage subdomains on built-in base domains.

vmail subdomains                                  # list
vmail subdomains --add team venumzmail.lol        # creates team.venumzmail.lol
vmail subdomains --remove team.venumzmail.lol

// 2026 venumzmail, Inc. All rights reserved.
// node sdk by @hanx - https://hanx.lol
// version 1.0.0
// https://www.npmjs.com/package/venumzmail
// This file is part of the venumzmail SDK, licensed under the MIT License.
// last modified: 2026-06-26 03:56 UTC

// JS/TS version of https://pypi.org/project/venumzmail/