Getting Started

Introduction

MinuteMail is a privacy-first disposable email service. Generate a temporary inbox in one click, receive emails instantly via WebSocket, and let everything auto-destruct when the timer runs out. No registration required for temporary mailboxes.

Instant

Mailbox ready in under 100ms

Private

Zero-retention, TLS everywhere

Temporary

Auto-destruct from 2–30 minutes

Core Concepts

Mailbox

A temporary email address with a TTL. Each mailbox has a unique random address and a session token for authentication.

Session Token

A secret token returned when a mailbox is created. Required for all authenticated API operations.

TTL

Time-to-live in minutes (2, 5, 10, 15, 20, or 30). When it hits zero, the mailbox and all data are permanently destroyed.

WebSocket

Real-time push channel. Connect once and receive email notifications instantly instead of polling.

Permanent Mailbox

Account-linked mailboxes that never expire. Requires registration. Unlimited, free.

Custom Alias

Choose your own @minutemail.xyz address. Create readable aliases that forward to your permanent mailbox.

Quick Start

Create a mailbox with a single API call:

bash
curl -X POST https://minutemail.xyz/api/mailbox \
  -H "Content-Type: application/json" \
  -d '{"duration": 10}'

Then poll for emails or connect via WebSocket:

bash
# Poll for emails
curl https://minutemail.xyz/api/mailbox/{id} \
  -H "Authorization: Bearer {sessionToken}"

# Or connect via WebSocket for real-time delivery
wscat -c "wss://minutemail.xyz/ws?mailboxId={id}&token={sessionToken}"

Architecture

Frontend

Next.js — server-rendered React with API routes

Storage

Redis — in-memory with RDB + AOF persistence

Mail

Postfix SMTP relaying to custom Node.js SMTP server

Real-time

WebSocket server for instant email push delivery

User Guide

Dashboard

The dashboard is your control center for managing temporary and permanent mailboxes, aliases, attachments, and privacy settings.

Temporary Inbox

Create and monitor disposable mailboxes with live countdown timers.

Permanent Mailboxes

Manage persistent email addresses that never expire.

Custom Aliases

Create readable @minutemail.xyz aliases.

Attachments

View and download all received attachments.

Privacy Report

See exactly what data MinuteMail stores about your account.

Reading Emails

Emails appear in real-time as they arrive. Click any email to read the full content. HTML emails are rendered safely in a sandboxed iframe. Plain-text emails are displayed with preserved formatting. Unread emails are marked with a blue dot.

Extending Sessions

Click the "Extend" button while your mailbox is active to add more time. You can extend in increments up to 30 minutes. The maximum total lifetime is capped at 60 minutes from the current moment.

Permanent Mailboxes

Registered users can create unlimited permanent mailboxes for free. Each mailbox requires a password set during creation, which enables independent login access — similar to Roundcube webmail.

FieldTypeDescription
Cost—Free, unlimited
FormatstringRandom or custom @minutemail.xyz address
PasswordstringRequired — each mailbox has its own login password
Login—Sign in at /mailbox with email + password, or use the direct link
StorageRedisUp to 100 emails per mailbox, persists until deleted
Features—Unread counts, mark-as-read, delete emails, change password, share link

Custom Aliases

Create human-readable aliases like [email protected] that forward to your permanent mailbox. Aliases can be created, renamed, and deleted from the Dashboard.

QR Generator

Generate QR codes for any of your mailbox addresses. Useful for sharing your disposable email on printed materials, slides, or mobile screens.

Privacy Report

The Privacy Report shows exactly what data MinuteMail stores about your account: username, email, creation date, mailbox count, and ticket history. No hidden data. No analytics profiles.

API Reference

Overview

All API endpoints are under https://minutemail.xyz/api. Responses are JSON. Authentication uses the Authorization: Bearer <sessionToken> header.

Base URL

https://minutemail.xyz/api

Create Mailbox

POST/api/mailbox

Create a new temporary mailbox. Duration defaults to 30 minutes.

FieldTypeDescription
durationnumberMinutes: 2, 5, 10, 15, 20, or 30. Default: 30
bash
curl -X POST https://minutemail.xyz/api/mailbox \
  -H "Content-Type: application/json" \
  -d '{"duration": 10}'

Response 201

json
{
  "id": "abc123def456",
  "address": "[email protected]",
  "createdAt": 1711738800000,
  "expiresAt": 1711739400000,
  "duration": 10,
  "sessionToken": "tok_abc123..."
}

Get Mailbox

GET/api/mailbox/:id

Retrieve mailbox metadata and all emails.

bash
curl https://minutemail.xyz/api/mailbox/abc123def456 \
  -H "Authorization: Bearer tok_abc123..."

Response 200

json
{
  "id": "abc123def456",
  "address": "[email protected]",
  "createdAt": 1711738800000,
  "expiresAt": 1711739400000,
  "emails": [
    {
      "id": "email_001",
      "from": "[email protected]",
      "subject": "Verify your email",
      "preview": "Click the link below to verify...",
      "receivedAt": 1711738900000,
      "read": false
    }
  ]
}

Get Email

GET/api/mailbox/:id/email/:emailId

Retrieve a specific email with full body content. Automatically marks the email as read.

bash
curl https://minutemail.xyz/api/mailbox/abc123def456/email/email_001 \
  -H "Authorization: Bearer tok_abc123..."

Response 200

json
{
  "id": "email_001",
  "from": "[email protected]",
  "fromName": "Example App",
  "to": "[email protected]",
  "subject": "Verify your email",
  "textBody": "Click: https://example.com/verify?t=...",
  "htmlBody": "<html>...</html>",
  "receivedAt": 1711738900000,
  "read": true,
  "attachments": []
}

Extend Mailbox

POST/api/mailbox/:id/extend

Extend the mailbox expiration. Cannot exceed 60 minutes total from the current moment.

FieldTypeDescription
minutesnumberMinutes to add (1–30). Default: 10
bash
curl -X POST https://minutemail.xyz/api/mailbox/abc123def456/extend \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tok_abc123..." \
  -d '{"minutes": 15}'

Delete Mailbox

DELETE/api/mailbox/:id

Permanently destroy a mailbox and all its data immediately.

bash
curl -X DELETE https://minutemail.xyz/api/mailbox/abc123def456 \
  -H "Authorization: Bearer tok_abc123..."

This action is irreversible. All emails, attachments, and metadata are permanently deleted.

Attachments

GET/api/mailbox/:id/email/:emailId/attachment/:filename

Download a specific attachment. Returns the raw file with appropriate Content-Type and Content-Disposition headers.

bash
curl -O https://minutemail.xyz/api/mailbox/abc123/email/email_001/attachment/report.pdf \
  -H "Authorization: Bearer tok_abc123..."

Error Codes

All errors follow a consistent format:

json
{ "error": "Human-readable error message" }
StatusMeaning
400Bad request — invalid parameters
401Unauthorized — missing or invalid session token
403Forbidden — IP is banned
404Not found — mailbox or email doesn't exist (or expired)
429Rate limited — too many requests
500Server error — unexpected failure
WebSocket

Connecting

Open a WebSocket connection to receive real-time email notifications for a mailbox.

WebSocket URL

wss://minutemail.xyz/ws?mailboxId={id}&token={sessionToken}

javascript
const ws = new WebSocket(
  "wss://minutemail.xyz/ws?mailboxId=abc123&token=tok_abc123..."
);

ws.onopen = () => console.log("Connected");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Event:", data.type, data);
};

Event Types

new_emailFired when a new email arrives
json
{
  "type": "new_email",
  "email": {
    "id": "email_001",
    "from": "[email protected]",
    "subject": "Verify your email",
    "preview": "Click the link below...",
    "receivedAt": 1711738900000
  }
}
mailbox_expiredFired when the mailbox TTL reaches zero
json
{ "type": "mailbox_expired", "mailboxId": "abc123def456" }

Connection closes shortly after this event.

pingpongKeepalive heartbeat

Respond with {"type":"pong"} within 30 seconds.

Keepalive

The server sends a ping every 30 seconds. Respond with a pong to keep the connection alive.

javascript
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "ping") {
    ws.send(JSON.stringify({ type: "pong" }));
    return;
  }
  // Handle other events...
};

Reconnection

Implement exponential backoff for reliable reconnection. Don't reconnect after close code 4003 (mailbox expired).

javascript
function connect(mailboxId, token) {
  let delay = 2000;
  const maxDelay = 30000;

  function attempt() {
    const ws = new WebSocket(
      `wss://minutemail.xyz/ws?mailboxId=${mailboxId}&token=${token}`
    );
    ws.onopen = () => { delay = 2000; };
    ws.onclose = (e) => {
      if (e.code === 4003) return; // Expired
      setTimeout(attempt, delay);
      delay = Math.min(delay * 2, maxDelay);
    };
    ws.onmessage = (e) => {
      const d = JSON.parse(e.data);
      if (d.type === "ping") ws.send('{"type":"pong"}');
    };
  }
  attempt();
}
FAQ

General

Privacy & Security

Technical