cf-temp-mail-agent-mail

Temp-Mail Agent Usage

Prerequisites

The user must first open the frontend (e.g. https://mail.example.com) in a browser and create or log into a mailbox address. This step may require passing a Turnstile CAPTCHA that agents cannot complete. After that, the Address JWT is displayed in the frontend UI and can be copied directly.

Inputs the user must provide

• BASE - API base URL, e.g. https://mail.example.com.
• JWT - Address JWT, visible and copyable from the frontend UI after creating or logging into a mailbox.
• (optional) SITE_PASSWORD - only if the deployment enabled x-custom-auth.

If anything is missing, ask the user before making requests.

Credential persistence

To avoid asking every time, save credentials to ~/.cf-temp-mail/credentials.json:

{
  "base": "https://mail.example.com",
  "jwt": "<ADDRESS_JWT>",
  "site_password": ""
}

On first use, if the file exists, read and use it. If not, ask the user and save for next time. Before each request, validate the JWT via GET /api/settings - if it returns 401, inform the user the JWT is expired and ask for a fresh one, then update the file.

Required headers

• Authorization: Bearer <JWT> - on every /api/* request.
• x-custom-auth: <SITE_PASSWORD> - only when the site requires it.
• x-lang: en or zh - optional, error-message language.

Do not send the Address JWT as x-user-token - that is a different JWT type and will yield 401 InvalidAddressCredentialMsg.

Primary path: parsed endpoints

Task	Method	Path	Returns
Address info	GET	/api/settings	{ address, send_balance }
List parsed mails	GET	/api/parsed_mails'limit=&offset=	{ results: [parsedMail], count }
Get one parsed mail	GET	/api/parsed_mail/:id	parsedMail