Use the Trivumo Node.js SDK to generate email addresses, wait for messages, and validate email workflows in your automated tests.

The Trivumo Node.js SDK makes it easy to test email-driven workflows such as account verification, password resets, magic links, invitations, and one-time passwords.

Installation

npm install trivumo

Usage

Create a Client

import { TrivumoClient } from 'trivumo';

const trivumo = new TrivumoClient({
  apiKey: process.env.TRIVUMO_API_KEY!,
  domain: 'sandbox.trivumo.com',
});

Generate an Email Address

const email = trivumo.generateEmail();

console.log(email);
// x7k2m9qp@sandbox.trivumo.com

With a custom username:

const email = trivumo.generateEmail('john');

console.log(email);
// john@sandbox.trivumo.com

Wait for an Email

const message = await trivumo.waitForMessage({
  to: email,
  subject: 'Verify your account',
});

The returned message includes:

Metadata
HTML content
Plain text content
Extracted links
Extracted images
Verification codes and OTPs
Email headers

Trigger an Action and Wait for an Email

const message = await trivumo.waitForMessageAfter(
  () => page.click('[type=submit]'),
  {
    to: email,
    subject: 'Verify your account',
  }
);

Only emails received after the action are considered.

Access Verification Codes

const message = await trivumo.waitForMessage({
  to: email,
});

const otp =
  message.html?.codes[0] ??
  message.text?.codes[0];

console.log(otp);

Access Links

const message = await trivumo.waitForMessage({
  to: email,
});

const verificationLink =
  message.html?.links[0]?.href;

await page.goto(verificationLink!);

Get a Message

const message = await trivumo.getMessage(
  referenceId
);

Search Messages

const messages = await trivumo.getMessages({
  to: email,
});

Example:

const messages = await trivumo.getMessages({
  subject: 'Password Reset',
  receivedAfter: Date.now() - 60_000,
});

API Reference

TrivumoClient

constructor

Creates a new client.

Parameter	Type
options	TrivumoClientOptions

const trivumo = new TrivumoClient({
  apiKey: process.env.TRIVUMO_API_KEY!,
  domain: 'sandbox.trivumo.com',
});

generateEmail

Generates a unique email address.

generateEmail(username?: string): string

waitForMessage

Waits until a matching email is received.

Parameter	Type
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

const message = await trivumo.waitForMessage({
  to: email,
});

waitForMessageAfter

Executes an action and waits for a matching email received afterward.

Parameter	Type
action	`() => Promise<unknown> \| unknown`
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

const message = await trivumo.waitForMessageAfter(
  () => page.click('[type=submit]'),
  {
    to: email,
  }
);

getMessage

Retrieves a message by its reference ID.

Parameter	Type
referenceId	string

Returns: MessageDetails

const message = await trivumo.getMessage(
  referenceId
);

getMessages

Searches for messages matching the supplied filters.

Parameter	Type
filters	MessageFilters

Returns: PaginatedResponse < Message >

const messages = await trivumo.getMessages({
  subject: 'Password Reset',
});

Type Reference

TrivumoClientOptions

interface TrivumoClientOptions {
  apiKey: string;
  domain: string;
  baseUrl?: string;
  timeout?: number;
  retries?: number;
}

Property	Type	Description
apiKey	string	Your Trivumo API key.
domain	string	Inbox domain assigned to your team.
baseUrl	string	Override the API endpoint.
timeout	number	HTTP request timeout in milliseconds.
retries	number	Retry attempts for transient failures.

MessageFilters

interface MessageFilters {
  subject?: string;
  from?: string;
  to?: string;
  receivedAfter?: number;
}

Property	Type	Description
subject	string	Filter by email subject.
from	string	Filter by sender address.
to	string	Filter by recipient address.
receivedAfter	number	Unix timestamp in milliseconds.

WaitForMessageOptions

interface WaitForMessageOptions {
  timeout?: number;
  pollInterval?: number;
}

Property	Type	Description
timeout	number	Maximum time to wait before throwing an error.
pollInterval	number	Time between polling attempts.

Message

interface Message {
  id: string;
  referenceId: string;
  subject: string;
  from: string;
  to: string;
  receivedAt: string;
}

Property	Type	Description
id	string	Internal message identifier.
referenceId	string	Stable message reference.
subject	string	Email subject.
from	string	Sender address.
to	string	Recipient address.
receivedAt	string	ISO timestamp when received.

interface Header {
  key: string;
  originalKey: string;
  value: string;
}

Property	Type	Description
key	string	Lowercase header name.
originalKey	string	Original header name.
value	string	Header value.

ExtractedLink

interface ExtractedLink {
  href: string;
  text: string | null;
}

Property	Type	Description
href	string	Destination URL.
text	string	null

ExtractedImage

interface ExtractedImage {
  alt: string | null;
  url: string | null;
  base64: string | null;
}

Property	Type	Description
alt	string	null
url	string	null
base64	string	null

MessageBodyPart

interface MessageBodyPart {
  body: string;
  codes: string[];
  links: ExtractedLink[];
  images: ExtractedImage[];
}

Property	Type
body	string
codes	string[]
links	ExtractedLink[]
images	ExtractedImage[]

MessageContent

interface MessageContent {
  headers: Header[];
  html: MessageBodyPart | null;
  text: MessageBodyPart | null;
}

Property	Type
headers	Header[]
html	MessageBodyPart
text	MessageBodyPart

MessageDetails

interface MessageDetails extends Message, MessageContent {}

Complete email including metadata, headers, HTML content, plain text content, extracted links, images, and verification codes.

Composed from:

Message
MessageContent

Example:

const message = await trivumo.waitForMessage({
  to: email,
});

console.log(message.subject);
console.log(message.html?.codes[0]);
console.log(message.html?.links[0]?.href);

PaginatedResponse

export interface PaginatedResponse<T> {
    page: number
    totalPages: number
    data: T[]
}

Property	Type
page	number
totalPages	number
data	T[]

Node.js

On this page