temp-mail

---
name: temp-mail
description: Temporary email helper backed by Vortex (vortex.email). Use when needing disposable addresses for signup flows: create a mailbox (random localpart), poll for messages, fetch and clear mailboxes.
homepage: https://vortex.skyfall.dev
metadata: {"clawdis":{"emoji":"✉️","requires":{"bins":["curl"]}}}
---

# temp-mail skill

This skill provides a Python CLI script to interact with the hosted Vortex API (GET /emails/{email}, DELETE /emails/{email}/clear).

Usage examples (scripts are in scripts/):

- create: generates a random localpart and prints an address for the provided domain
- fetch: queries the Vortex HTTP API to list messages for an address
- poll: wait until messages arrive or timeout
- clear: delete all messages for an address

Run with uv: `uv run {baseDir}/scripts/temp_mail.py` (script includes shebang and metadata header similar to the hn skill)

Examples:

```bash
# generate a random address
uv run {baseDir}/scripts/temp_mail.py create

# fetch messages for an address
uv run {baseDir}/scripts/temp_mail.py fetch [email protected]

# poll until messages arrive (timeout 60s)
uv run {baseDir}/scripts/temp_mail.py poll [email protected] --timeout 60

# clear mailbox
uv run {baseDir}/scripts/temp_mail.py clear [email protected]
```

Defaults:
- VORTEX_URL: https://vtx-api.skyfall.dev
- default domain: skyfall.dev (override with VORTEX_DOMAIN env var)

Install

```bash
# create a venv and install deps (unix)
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r scripts/requirements.txt

# or using uv which creates an ephemeral venv for you, e.g.
uv run {baseDir}/scripts/temp_mail.py create
```

Notes:
- script uses httpx for requests; rich is optional and omitted from requirements
- random username generation mirrors the frontend behavior (lowercase alphanumeric), attempted to replicate falso randUserName behavior
- hosted instance includes multiple domains, e.g., dash.dino.icu, skyfall.dev, etc. When creating addresses, choose a domain from that list or let the script use the default