Documentation

Everything you need to integrate OneShotMail into your projects, pipelines, and workflows.

Quick Start

1. Get your API key

2. Install the SDK

pip install oneshot-mail

3. Create and receive

from oneshot import OneShotClient

client = OneShotClient(api_key="osm_live_...")
address = client.create(ttl=300, label="my-test")
# Use address.address in your test...
email = client.wait_for_email(address.id, timeout=60)
print(email.subject)

Concepts

Understand addresses, modes (receive/send), TTLs, labels, and credits.

API Reference

Complete REST API documentation with request/response examples for every endpoint.

CLI Reference

Full command reference for the oneshot CLI tool. Install, configure, and use from your terminal.

Python SDK

pip install oneshot-mail. Integrations for Behave, pytest, and unittest.

Go SDK

go get github.com/oneshotmail/oneshot-go. Integrations for testing and testify.

Ruby SDK

gem install oneshot-mail. Integrations for Cucumber and RSpec.

JavaScript SDK

npm install oneshot-mail. Integrations for Playwright, Cypress, and Jest.

Java SDK

Maven oneshot-mail. Integrations for JUnit 5 and Cucumber-JVM.

MCP Server

Give AI agents an inbox. Installation for Claude Desktop, Cursor, and Windsurf.

BDD Integration Guide

Full worked examples for Cucumber (Ruby), Behave (Python), and Playwright (JS).

Billing & Usage

Plans, credits, quotas, the free tier queue, and how billing works.

Security

How we handle your email data, encryption, retention, and deletion.