REST API

Mail1s.net APIScripts & automation

REST API to create temp addresses, read mail and manage inboxes from your script / server.

REST APIBearer TokenJSON responsesCORS *

Authentication

Every request must include one of these headers:

Authorization:

Bearer <api_key>

— OAuth standard, preferred.

X-API-Key:

<api_key>

— handy for tools that don't accept Bearer.

You don't have an API key yet. Create one on Profile — takes one click.

Every endpoint returns JSON. Errors look like { "error": "..." } with the appropriate HTTP status (401 wrong key, 403 forbidden, 404 not found, 429 over quota, 400 bad input).

CORS is * — so you can call directly from the browser if you want.

Mail1s.net MCP Server

MCP

For AI agents (Cursor, Claude, Codex…)

Agents call Temp Mail tools over Streamable HTTP. Pass the free API key or your personal key in the Authorization header.

https://mail1s.net/api/mcp

Streamable HTTP · Bearer / X-API-Key

Tools

01
list_domains
List Mail1s domains available for creating temporary email addresses.
02
create_address
Create a temporary email address on a Mail1s domain. Omit localPart to auto-generate a random local part.
03
list_addresses
List temporary addresses owned by this API key (with optional unread/total counts).
04
list_messages
List messages received by a temporary address (newest first).
05
read_message
Read full content (text + html) of one message in a mailbox.
06
delete_message
Permanently delete one message from a mailbox.
07
delete_address
Remove a temporary address from the key’s list (also deletes messages by default).

Connect your client

1. Add the server:

$ claude mcp add --transport http mail1s https://mail1s.net/api/mcp --header "Authorization: Bearer <API_KEY>"

2. Restart Claude Code (or start a new conversation).
3. Select mail1s and authenticate:
```
1/mcp
```
You should see mail1s in the list of active MCP servers.

Suggested agent flow

01
list_domains
Pick a public domain
02
create_address
Create a temp mailbox
03
list_messages
Poll OTP / verify
04
read_message
Read full content

Node.js example (fetch)

Node.js / Browser

const API_KEY = '<API_KEY>';
const BASE    = 'https://your-host';

async function api(path, init = {}) {
  const r = await fetch(BASE + path, {
    ...init,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...(init.headers ?? {}),
    },
  });
  if (!r.ok) throw new Error((await r.json()).error ?? r.statusText);
  return r.json();
}

// // 1. Create an address
const addr = await api('/api/v1/addresses', {
  method: 'POST',
  body: JSON.stringify({ domain: 'mail1s.net' }),
});
// console.log('Created:', addr.address);

// // 2. Wait a few seconds for mail to arrive…
await new Promise((r) => setTimeout(r, 5000));

// // 3. List inbox
const inbox = await api(`/api/v1/addresses/${encodeURIComponent(addr.address)}/messages`);
// console.log('Mail count:', inbox.count);

// // 4. Read the latest message
if (inbox.messages[0]) {
  const msg = await api(
    `/api/v1/addresses/${encodeURIComponent(addr.address)}/messages/${inbox.messages[0].id}`,
  );
  console.log('From:', msg.from, '— Subject:', msg.subject);
}

// // 5. Delete the address and clean up the inbox
await api(`/api/v1/addresses/${encodeURIComponent(addr.address)}`, { method: 'DELETE' });

Quotas (mails per day, saved addresses) follow your paid plan at /upgrade.