Inbound Mailboxes For Agents

Stable mailbox identity, bound to a key.

Same key, same mailbox. Different key, different mailbox. Pay monthly. Read inbound mail over IMAP. Pricing: 1 EUR/month per mailbox (100 MB storage). No SMTP. No outbound sending.

Build: 145 | Cache buster: 7e77aa0-145-1

The key is the mailbox identity. EdProof is the key proof used to identify the mailbox. It is not a login account, not a billing email, and not a payment method.
The billing email is only for billing. The billing email is only where the invoice goes.
This product is inbound-only. You get inbound delivery and IMAP read access. You do not get SMTP submission or relay access.
How to start Health

Bring a key

If your agent already has an Ed25519 key, use it. If it does not, generate one with ssh-keygen -t ed25519 -f identity -C "entity@context".

Claim a mailbox

Get a challenge from POST /v1/auth/challenge, sign it with your private key, then call POST /v1/mailboxes/claim.

Pay and read mail

Pay from the emailed link. Get a new challenge, sign it, then call POST /v1/access/resolve to get IMAP credentials.

Give this to your agent

## Agent Instructions — TrueVIP Access Mailbox API Full skill document: GET /docs/agent-api-skill.md (or read docs/agent-api-skill.md from the repo). ### Quick Start 1. Generate an Ed25519 key (or reuse an existing one — same key = same mailbox): ssh-keygen -t ed25519 -f identity -N "" -C "agent@context" 2. Get a challenge (expires in 30 seconds): POST /v1/auth/challenge {"public_key": "ssh-ed25519 AAAA..."} 3. Sign the challenge — IMPORTANT: strip armor headers and newlines: SIGNATURE=$(echo -n "$CHALLENGE" | ssh-keygen -Y sign -f identity -n edproof | sed '1d;$d' | tr -d '\n') The namespace MUST be "edproof" (-n edproof). The signature MUST be a single base64 line without BEGIN/END headers. 4. Claim a mailbox: POST /v1/mailboxes/claim {"billing_email":"...","edproof":"ssh-ed25519 AAAA...","challenge":"...","signature":"..."} If "usable":true → access_token is in the response. If "usable":false → present payment_url to user. 5. After payment, get a NEW challenge, sign it, then resolve access: POST /v1/access/resolve {"protocol":"imap","edproof":"ssh-ed25519 AAAA...","challenge":"...","signature":"..."} Returns IMAP host, port, username, password, and access_token. 6. Read messages (no IMAP library needed): POST /v1/imap/messages {"access_token":"...","unread_only":true,"include_body":true} POST /v1/imap/messages/get {"access_token":"...","uid":1,"include_body":true} ### Common Errors - "challenge expired" → get a new challenge (30s TTL) - "signature verification failed" → check: (1) signed exact challenge string (2) used -n edproof (3) stripped armor+newlines - 409 "waiting_payment" → payment not yet completed Do not ask the operator unless key generation is impossible or the same mailbox is required but the existing key is unavailable.
  1. If no EdProof key exists locally, generate one and continue.
  2. If you want the same mailbox later, keep the same EdProof key. A different key gets a different mailbox.
  3. Call POST /v1/auth/challenge with public_key to get a challenge string.
  4. Sign the challenge with your Ed25519 private key.
  5. Call POST /v1/mailboxes/claim with billing_email, edproof, challenge, and signature.
  6. Pay from the emailed payment link.
  7. Request a new challenge, sign it, then call POST /v1/access/resolve with protocol=imap, edproof, challenge, and signature.
  8. Read mail using the returned IMAP details.

Reading mail

Two options: HTTP API (easiest for agents) or direct IMAP (for mail clients and raw protocol access).

Option A: HTTP API (recommended for agents)

After payment, resolve access credentials, then use the HTTP endpoints. No IMAP library required.

## Step 1 — resolve credentials curl -X POST https://truevipaccess.com/v1/access/resolve \ -H 'Content-Type: application/json' \ -d '{"protocol":"imap","edproof":"<your-edproof>"}' # Response: # {"mailbox_id":"...","host":"mail.truevipaccess.com","port":143, # "username":"[email protected]","password":"...","email":"..."} ## Step 2 — list messages curl -X POST https://truevipaccess.com/v1/imap/messages \ -H 'Authorization: Bearer <api_token>' \ -H 'Content-Type: application/json' \ -d '{"access_token":"<mailbox_access_token>","unread_only":true,"include_body":true}' ## Step 3 — get a single message by UID curl -X POST https://truevipaccess.com/v1/imap/messages/get \ -H 'Authorization: Bearer <api_token>' \ -H 'Content-Type: application/json' \ -d '{"access_token":"<mailbox_access_token>","uid":1,"include_body":true}'

Agent note: access_token comes from the mailbox claim/create response (returned when mailbox is usable). api_token is the account-level auth token used in the Authorization header.

Option B: Direct IMAP

Connect with any IMAP client using the credentials from /v1/access/resolve.

## Python (TLS on port 993) import imaplib imap = imaplib.IMAP4_SSL("mail.truevipaccess.com", 993) imap.login(username, password) imap.select("INBOX", readonly=True) _, data = imap.search(None, "UNSEEN") for num in data[0].split(): _, msg = imap.fetch(num, "(RFC822)") print(msg[0][1]) imap.logout() ## curl (test connectivity) curl -v --url "imaps://mail.truevipaccess.com:993/INBOX" \ --user "[email protected]:password"
Mail client settings (Thunderbird, Apple Mail, etc.)
  • Protocol: IMAP
  • Host: mail.truevipaccess.com
  • Port: 993 (TLS) or 143 (STARTTLS)
  • Encryption: SSL/TLS (recommended) or STARTTLS
  • Authentication: Normal password
  • Username/Password: from the /v1/access/resolve response