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

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

Installation

pip install trivumo

Usage

Create a Client

from trivumo import TrivumoClient

trivumo = TrivumoClient(
    apiKey="your_api_key",
    domain="sandbox.trivumo.com",
)

Generate an Email Address

email = trivumo.generate_email()

print(email)
# x7k2m9qp@sandbox.trivumo.com

With a custom username:

email = trivumo.generate_email("john")

print(email)
# john@sandbox.trivumo.com

Wait for an Email

message = trivumo.wait_for_message(
    {
        "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

def trigger_action():
    page.click("[type=submit]")

message = trivumo.wait_for_message_after(
    trigger_action,
    {
        "to": email,
        "subject": "Verify your account",
    },
)

Only emails received after the action are considered.

Trigger an Async Action and Wait for an Email

async def trigger_action():
    await page.click("[type=submit]")

message = await trivumo.wait_for_message_after_async(
    trigger_action,
    {
        "to": email,
        "subject": "Verify your account",
    },
)

Only emails received after the action are considered.

Access Verification Codes

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

otp = (
    message.html.codes[0]
    if message.html and message.html.codes
    else None
)

print(otp)

Access Links

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

verification_link = (
    message.html.links[0].href
    if message.html and message.html.links
    else None
)

print(verification_link)

Get a Message

message = trivumo.get_message(
    reference_id
)

Search Messages

messages = trivumo.get_messages(
    {
        "to": email,
    }
)

Example:

messages = trivumo.get_messages(
    {
        "subject": "Password Reset",
        "receivedAfter": int(time.time() * 1000) - 60000,
    }
)

API Reference

TrivumoClient

Constructor

Creates a new client.

Parameter	Type
apiKey	str
domain	str
baseUrl	str
timeout	float
retries	int

generate_email

Generates a unique email address.

generate_email(username: str | None = None) -> str

wait_for_message

Waits until a matching email is received.

Parameter	Type
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

wait_for_message_after

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

Parameter	Type
action	Callable
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

message = trivumo.wait_for_message_after(
    trigger_action,
    {
        "to": email,
    }
)

wait_for_message_after_async

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

Parameter	Type
action	Callable
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

message = await trivumo.wait_for_message_after_async(
    trigger_action,
    {
        "to": email,
    }
)

get_message

Retrieves a message by its reference ID.

Parameter	Type
reference_id	str

Returns: MessageDetails

message = trivumo.get_message(
    reference_id
)

get_messages

Searches for messages matching the supplied filters.

Parameter	Type
filters	MessageFilters

Returns: PaginatedResponse[Message]

messages = trivumo.get_messages(
    {
        "subject": "Password Reset",
    }
)

Type Reference

TrivumoClientOptions

class TrivumoClientOptions(TypedDict):
    apiKey: str
    domain: str
    baseUrl: str
    timeout: float
    retries: int

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

MessageFilters

class MessageFilters(TypedDict):
    subject: str
    fromEmail: str
    to: str
    receivedAfter: int
    page: int

Property	Type	Description
subject	str	Filter by email subject.
fromEmail	str	Filter by sender address.
to	str	Filter by recipient address.
receivedAfter	int	Unix timestamp in milliseconds.
page	int	Page number for pagination.

WaitForMessageOptions

class WaitForMessageOptions(TypedDict):
    timeout: int
    pollInterval: int

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

Message

@dataclass
class Message:
    id: str
    referenceId: str
    subject: str
    fromEmail: str
    to: str
    receivedAt: str

Property	Type
id	str
referenceId	str
subject	str
fromEmail	str
to	str
receivedAt	str

@dataclass
class Header:
    key: str
    originalKey: str
    value: str

Property	Type
key	str
originalKey	str
value	str

ExtractedLink

@dataclass
class ExtractedLink:
    href: str
    text: str | None

Property	Type
href	str
text	str

ExtractedImage

@dataclass
class ExtractedImage:
    alt: str | None
    url: str | None
    base64: str | None

Property	Type
alt	str
url	str
base64	str

MessageBodyPart

@dataclass
class MessageBodyPart:
    body: str
    codes: list[str]
    links: list[ExtractedLink]
    images: list[ExtractedImage]

Property	Type
body	str
codes	list[str]
links	list[ExtractedLink]
images	list[ExtractedImage]

MessageContent

@dataclass
class MessageContent:
    headers: list[Header]
    html: MessageBodyPart | None
    text: MessageBodyPart | None

Property	Type
headers	list[Header]
html	MessageBodyPart
text	MessageBodyPart

PaginatedResponse

@dataclass
class PaginatedResponse(TypedDict, Generic[T]):
	page: int
	totalPages: int
	data: list[T]

Property	Type
page	int
totalPages	int
data	list[T]

MessageDetails

@dataclass
class MessageDetails(Message, MessageContent):
    pass

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

Extends:

Message
MessageContent

Example:

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

print(message.subject)
print(message.html.codes[0] if message.html else None)
print(message.html.links[0].href if message.html and message.html.links else None)

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

Installation

pip install trivumo

Usage

Create a Client

from trivumo import TrivumoClient

trivumo = TrivumoClient(
    apiKey="your_api_key",
    domain="sandbox.trivumo.com",
)

Generate an Email Address

email = trivumo.generate_email()

print(email)
# x7k2m9qp@sandbox.trivumo.com

With a custom username:

email = trivumo.generate_email("john")

print(email)
# john@sandbox.trivumo.com

Wait for an Email

message = trivumo.wait_for_message(
    {
        "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

def trigger_action():
    page.click("[type=submit]")

message = trivumo.wait_for_message_after(
    trigger_action,
    {
        "to": email,
        "subject": "Verify your account",
    },
)

Only emails received after the action are considered.

Trigger an Async Action and Wait for an Email

async def trigger_action():
    await page.click("[type=submit]")

message = await trivumo.wait_for_message_after_async(
    trigger_action,
    {
        "to": email,
        "subject": "Verify your account",
    },
)

Only emails received after the action are considered.

Access Verification Codes

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

otp = (
    message.html.codes[0]
    if message.html and message.html.codes
    else None
)

print(otp)

Access Links

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

verification_link = (
    message.html.links[0].href
    if message.html and message.html.links
    else None
)

print(verification_link)

Get a Message

message = trivumo.get_message(
    reference_id
)

Search Messages

messages = trivumo.get_messages(
    {
        "to": email,
    }
)

Example:

messages = trivumo.get_messages(
    {
        "subject": "Password Reset",
        "receivedAfter": int(time.time() * 1000) - 60000,
    }
)

API Reference

TrivumoClient

Constructor

Creates a new client.

Parameter	Type
apiKey	str
domain	str
baseUrl	str
timeout	float
retries	int

generate_email

Generates a unique email address.

generate_email(username: str | None = None) -> str

wait_for_message

Waits until a matching email is received.

Parameter	Type
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

wait_for_message_after

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

Parameter	Type
action	Callable
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

message = trivumo.wait_for_message_after(
    trigger_action,
    {
        "to": email,
    }
)

wait_for_message_after_async

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

Parameter	Type
action	Callable
filters	MessageFilters
options	WaitForMessageOptions

Returns: MessageDetails

message = await trivumo.wait_for_message_after_async(
    trigger_action,
    {
        "to": email,
    }
)

get_message

Retrieves a message by its reference ID.

Parameter	Type
reference_id	str

Returns: MessageDetails

message = trivumo.get_message(
    reference_id
)

get_messages

Searches for messages matching the supplied filters.

Parameter	Type
filters	MessageFilters

Returns: PaginatedResponse[Message]

messages = trivumo.get_messages(
    {
        "subject": "Password Reset",
    }
)

Type Reference

TrivumoClientOptions

class TrivumoClientOptions(TypedDict):
    apiKey: str
    domain: str
    baseUrl: str
    timeout: float
    retries: int

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

MessageFilters

class MessageFilters(TypedDict):
    subject: str
    fromEmail: str
    to: str
    receivedAfter: int
    page: int

Property	Type	Description
subject	str	Filter by email subject.
fromEmail	str	Filter by sender address.
to	str	Filter by recipient address.
receivedAfter	int	Unix timestamp in milliseconds.
page	int	Page number for pagination.

WaitForMessageOptions

class WaitForMessageOptions(TypedDict):
    timeout: int
    pollInterval: int

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

Message

@dataclass
class Message:
    id: str
    referenceId: str
    subject: str
    fromEmail: str
    to: str
    receivedAt: str

Property	Type
id	str
referenceId	str
subject	str
fromEmail	str
to	str
receivedAt	str

@dataclass
class Header:
    key: str
    originalKey: str
    value: str

Property	Type
key	str
originalKey	str
value	str

ExtractedLink

@dataclass
class ExtractedLink:
    href: str
    text: str | None

Property	Type
href	str
text	str

ExtractedImage

@dataclass
class ExtractedImage:
    alt: str | None
    url: str | None
    base64: str | None

Property	Type
alt	str
url	str
base64	str

MessageBodyPart

@dataclass
class MessageBodyPart:
    body: str
    codes: list[str]
    links: list[ExtractedLink]
    images: list[ExtractedImage]

Property	Type
body	str
codes	list[str]
links	list[ExtractedLink]
images	list[ExtractedImage]

MessageContent

@dataclass
class MessageContent:
    headers: list[Header]
    html: MessageBodyPart | None
    text: MessageBodyPart | None

Property	Type
headers	list[Header]
html	MessageBodyPart
text	MessageBodyPart

PaginatedResponse

@dataclass
class PaginatedResponse(TypedDict, Generic[T]):
	page: int
	totalPages: int
	data: list[T]

Property	Type
page	int
totalPages	int
data	list[T]

MessageDetails

@dataclass
class MessageDetails(Message, MessageContent):
    pass

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

Extends:

Message
MessageContent

Example:

message = trivumo.wait_for_message(
    {
        "to": email,
    }
)

print(message.subject)
print(message.html.codes[0] if message.html else None)
print(message.html.links[0].href if message.html and message.html.links else None)

Python

On this page

Python

On this page