---
name: reseev-email
description: Create and manage email inboxes for AI agents via the Reseev API. Use this skill when the user or agent needs to create an email address, send email, read received messages, or set up email webhooks. Zero signup required.
version: 1.0.0
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, TodoWrite, Task
---

# Reseev Email Skill

Give any AI agent a working email address in one API call. No signup, no API keys, no human-in-the-loop.

**API Base URL**: `https://api.reseev.dev/v1`

## When to Use This Skill

Use this skill when:
- The agent needs its own email address to send or receive email
- The user asks to "create a mailbox", "send an email", "check email", or "set up a webhook"
- A workflow requires email verification, notifications, or communication
- You need a disposable or temporary email identity for a task

## Core Workflow

### 1. Create an Inbox (No Auth Required)

```bash
curl -s -X POST "https://api.reseev.dev/v1/inbox" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Response (201):
```json
{
  "id": "inbox_abc123",
  "address": "my-agent-x4k2@reseev.dev",
  "token": "tok_secret_value_shown_once",
  "created_at": "2026-01-01T00:00:00Z",
  "expires_at": "2026-01-31T00:00:00Z",
  "plan": "free",
  "limits": {
    "sends_per_day": 20,
    "receives_per_day": 200,
    "storage_mb": 10,
    "attachment_max_mb": 5
  }
}
```

**CRITICAL**: The `token` is shown ONLY ONCE. Store it immediately. You will need it for all subsequent requests.

The `name` field is optional. If provided, it becomes the prefix of the email address (e.g., `my-agent-x4k2@reseev.dev`). If omitted, a random address is generated.

### 2. Send an Email

```bash
curl -s -X POST "https://api.reseev.dev/v1/inbox/{INBOX_ID}/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {TOKEN}" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from my agent",
    "text": "This email was sent by an AI agent via reseev.dev"
  }'
```

Response (202):
```json
{
  "id": "msg_xyz789",
  "status": "queued",
  "to": ["recipient@example.com"]
}
```

**Send fields**:
- `to` (required): string or string[] — recipient(s)
- `subject` (required): string
- `text`: plain text body (at least one of text/html required)
- `html`: HTML body (at least one of text/html required)
- `cc`: string[] — CC recipients
- `bcc`: string[] — BCC recipients
- `reply_to`: string — Reply-To address

### 3. Read Messages

List all messages in the inbox:

```bash
curl -s "https://api.reseev.dev/v1/inbox/{INBOX_ID}/messages" \
  -H "Authorization: Bearer {TOKEN}"
```

Get a specific message:

```bash
curl -s "https://api.reseev.dev/v1/inbox/{INBOX_ID}/messages/{MSG_ID}" \
  -H "Authorization: Bearer {TOKEN}"
```

**Query params for listing**:
- `limit`: max messages (default 20, max 100)
- `cursor`: pagination cursor from previous response
- `since`: ISO8601 timestamp — only messages after this time

### 4. Set a Webhook (Optional)

Get notified on every incoming email:

```bash
curl -s -X PUT "https://api.reseev.dev/v1/inbox/{INBOX_ID}/webhook" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {TOKEN}" \
  -d '{"url": "https://your-server.com/email-hook"}'
```

### 5. Get Inbox Details

```bash
curl -s "https://api.reseev.dev/v1/inbox/{INBOX_ID}" \
  -H "Authorization: Bearer {TOKEN}"
```

### 6. Delete Inbox

```bash
curl -s -X DELETE "https://api.reseev.dev/v1/inbox/{INBOX_ID}" \
  -H "Authorization: Bearer {TOKEN}"
```

## Implementation Guidelines

When implementing email functionality for the user:

1. **Always use Python or Node.js `fetch`/`axios` for JSON payloads** — avoid shell-escaping issues with curl and special characters. If you must use curl, write the JSON payload to a temp file first and use `-d @/tmp/payload.json`.

2. **Store credentials safely** — save the inbox ID and token to a `.env` file, a local config, or memory. Never log the token in plaintext to the user unless they ask.

3. **Check for existing inbox first** — before creating a new inbox, check if the user already has one stored (in `.env`, project config, or conversation context).

4. **Handle errors gracefully**:
   - `401`: Invalid or expired token
   - `404`: Inbox not found (may have been deleted or expired)
   - `429`: Rate limit hit (20 sends/day, 50/week on free tier)
   - `502`: Upstream send failure — retry once

5. **Free tier limits**:
   - 20 sends per day, 50 per week
   - 200 receives per day
   - 10 MB storage
   - 5 MB max attachment
   - 7-day message retention
   - 30-day inbox expiry
   - Max 5 recipients per send

## Full Endpoint Reference

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/v1/inbox` | none | Create inbox |
| GET | `/v1/inbox/:id` | token | Get inbox details |
| DELETE | `/v1/inbox/:id` | token | Delete inbox |
| POST | `/v1/inbox/:id/send` | token | Send email |
| GET | `/v1/inbox/:id/messages` | token | List messages |
| GET | `/v1/inbox/:id/messages/:msg_id` | token | Get single message |
| DELETE | `/v1/inbox/:id/messages/:msg_id` | token | Delete message |
| PUT | `/v1/inbox/:id/webhook` | token | Set webhook URL |
| GET | `/v1/health` | none | Health check |

## Machine-Readable Resources

- Service manifest: `https://reseev.dev/.well-known/agent.json`
- LLM docs: `https://reseev.dev/llms.txt`
- Website: `https://reseev.dev`