Quick Start

Go from zero to receiving your first email in under 2 minutes.

Install the SDK

Choose your language and install the OneShotMail SDK:

# Python
pip install oneshot-mail

# Go
go get github.com/oneshotmail/oneshot-go

# Ruby
gem install oneshot-mail

# JavaScript / TypeScript
npm install oneshot-mail

# Java (Maven)
# Add to pom.xml — see the Java SDK guide

Set your API key

Get your API key from app.oneshotemail.com and export it as an environment variable:

export ONESHOT_API_KEY="osm_live_your_api_key_here"

Or pass it directly when creating the client.

Receive your first email (Python)

import oneshot

inbox = oneshot.create()
print(f"Send an email to: {inbox.address}")

email = inbox.wait_for_email()

print(f"From: {email.from_address}")
print(f"Subject: {email.subject}")
print(f"Body: {email.text_body}")

That is it. Three lines. The address auto-deletes after the TTL expires.

Use it in a test

The real power of OneShotMail is in automated tests. Here is a pytest example:

import oneshot
import pytest

def test_signup_sends_verification_email(app_client):
    inbox = oneshot.create(label="test-signup")

    app_client.post("/signup", json={"email": inbox.address, "name": "Test User"})

    email = inbox.wait_for_email(timeout=30)

    assert "Verify your account" in email.subject
    assert "Test User" in email.text_body

Send a one-shot email

You can also send a single email from a disposable address. This is useful for testing your app’s inbound email processing:

import oneshot

result = oneshot.send(
    to="intake@myapp.com",
    subject="Test invoice submission",
    text_body="Please process the attached invoice.",
    attachments=[("invoice.pdf", open("fixtures/invoice.pdf", "rb").read())],
)
print(f"Sent from: {result.address}")
print(f"Status: {result.status}")

Other languages

Every SDK provides the same core methods. Here are quick examples for each:

Go

package main

import (
    "context"
    "fmt"

    "github.com/oneshotmail/oneshot-go"
)

func main() {
    client := oneshot.NewClient("osm_live_your_api_key")
    ctx := context.Background()

    inbox, _ := client.Create(ctx, nil)
    fmt.Println("Send email to:", inbox.Address)

    email, _ := inbox.WaitForEmail(ctx, nil)
    fmt.Println("Subject:", email.Subject)
}

Ruby

require "oneshot"

client = OneShot::Client.new(api_key: "osm_live_your_api_key")
inbox = client.create
puts "Send email to: #{inbox.address}"

email = inbox.wait_for_email
puts "Subject: #{email.subject}"

JavaScript / TypeScript

import { OneShotClient } from "oneshot-mail";

const client = new OneShotClient("osm_live_your_api_key");

const inbox = await client.create();
console.log(`Send email to: ${inbox.address}`);

const email = await inbox.waitForEmail();
console.log(`Subject: ${email.subject}`);

Java

import com.oneshotmail.OneShotClient;

var client = new OneShotClient("osm_live_your_api_key");
var inbox = client.create();
System.out.println("Send email to: " + inbox.address);

var email = inbox.waitForEmail();
System.out.println("Subject: " + email.subject);

What next?

Edit this page on GitHub