EmptyInbox
Zero-config disposable email inboxes for AI agents: create, read mail, await verify codes.
Open source Open in the app JSON README (API)
About
Zero-config disposable email inboxes for AI agents: create, read mail, await verify codes.
Details
- Kind
- MCP servers
- Topic
- Communication
- Publisher
- cnohall
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.1
- Stars
- 4
- Forks
- 1
- Last push
- 2026-09-11T04:58:43Z
- Repository state
- ativo
- Language
- HTML
- Added
- 2026-09-11 04:03:01
- Updated
- 2026-09-11 04:03:01
- Origin id
io.github.cnohall/emptyinbox
README
# EmptyInbox
Disposable email inbox API for AI agents and developers. Create temporary email addresses, receive messages, and read content — via REST API or MCP server.
**Live at [emptyinbox.me](https://emptyinbox.me)**
## MCP Server (Claude / Claude Code / any MCP agent)
```json
{
"mcpServers": {
"emptyinbox": {
"command": "npx",
"args": ["emptyinbox-mcp"],
"env": {
"EMPTYINBOX_API_KEY": "your_api_key_here"
}
}
}
}
```
Get your API key at https://emptyinbox.me/settings.html
## REST API
Base URL: `https://emptyinbox.me/api`
Auth: `Authorization: Bearer <api_key>`
OpenAPI spec: `https://emptyinbox.me/openapi.yaml`
```bash
# Create an inbox
curl -X POST -H "Authorization: Bearer YOUR_KEY" https://emptyinbox.me/api/inbox
# List messages — filter to one inbox, only what arrived since the last poll
curl -H "Authorization: Bearer YOUR_KEY" \
"https://emptyinbox.me/api/messages?inbox=ADDRESS&since=1711234000&include_body=false"
# Read a message
curl -H "Authorization: Bearer YOUR_KEY" https://emptyinbox.me/api/message/MSG_ID
# ...or as flat text, ready to drop into a prompt
curl -H "Authorization: Bearer YOUR_KEY" "https://emptyinbox.me/api/message/MSG_ID?format=text"
```
Every message comes back parsed, so nothing has to pick through the HTML:
```json
{
"subject": "Confirm your email address",
"from_name": "Example App",
"from_email": "noreply@example.com",
"received_at": "2024-03-23T21:36:07Z",
"type": "verification",
"code": "482910",
"action_url": "https://example.com/verify?token=abc123",
"links": [{ "url": "https://example.com/verify?token=abc123", "text": "Verify your email" }],
"preview": "Your verification code is 482910. It expires in 10 minutes.",
"text": "Your verification code is 482910. It expires in 10 minutes."
}
```
`text` is the body flattened to plain text (from the HTML part when there is no text
part), `code` is the best one-time code found, `action_url` the single link worth
opening. `?format=raw` still returns the untouched MIME parts.
## Typical agent workflow
1. `POST /api/inbox` → get a disposable address
2. Use that address in an external signup or verification flow
3. `GET /api/messages?inbox=<address>&since=<last timestamp>` → poll until the verification email appears
4. Read `code` or `action_url` straight off the message — the API extracts both
## Local Development
### Backend (Flask, port 5000)
```powershell
cd api
pipenv install
pipenv run create_db # first run only — creates SQLite DB
pipenv run dev # starts python tempmail_api.py with CORS + /api prefix
```
**`api/.env` for local dev:**
```env
DOMAIN=localhost:8000
SECRET=any_random_string
FLASK_ENV=development
BLOCKONOMICS_API_KEY=<key>
USDT_RECEIVING_ADDRESS=<address>
MATCH_CALLBACK=ngrok
```
### Frontend (static, port 8000)
```powershell
cd static
python -m http.server 8000
```
Open http://localhost:8000. The JS auto-detects localhost and hits `http://localhost:5000` for the API (`static/utils/constants.js`).
---
## Self-hosting
### Requirements
- Ubuntu server
- Python 3 + pipenv
- Nginx
- Postfix
### Setup
**1. Clone and configure**
```bash
git clone https://github.com/blockonomics/emptyinbox-me
cd emptyinbox-me/api
cp .env.example .env # fill in your values
```
**.env variables:**
```
DOMAIN=yourdomain.com
SECRET=your_postfix_webhook_secret
FLASK_ENV=production
BLOCKONOMICS_API_KEY=your_blockonomics_api_key
USDT_RECEIVING_ADDRESS=your_usdt_address
MATCH_CALLBACK=https://yourdomain.com/api/payments/callback
```
**2. Database**
```bash
pipenv install
pipenv run create_db
```
**3. Gunicorn**
```bash
pipenv run start
```
**4. Nginx**
```bash
sudo cp nginx/emptyinbox_nginx.conf /etc/nginx/sites-available/emptyinbox_nginx.conf
sudo nginx -t && sudo systemctl reload nginx
```
**5. Postfix**
```bash
sudo apt install postfix # select "No configuration"
sudo cp /usr/share/postfix/main.cf.debian /etc/postfix/main.cf
sudo postfix/setup_postfix.sh YOUR_HOSTNAME YOUR_DOMAIN YOUR_SECRET
```
## Pricing
- Free: 5 inboxes per account
- Paid: 1 USDT per 10 additional inboxes (via Blockonomics — no credit card, no KYC)