# YYDS Mail API > Temporary email service with custom domain support, real-time WebSocket inbox, and developer-friendly REST API. > Base URL: https://maliapi.215.im/v1 ## Authentication (use one of three methods) - Bearer Token (JWT): Authorization: Bearer (from OAuth login, short-lived) - API Key: X-API-Key: AC-xxx (long-lived, created in dashboard, with domain scope) - Temp Token: Authorization: Bearer (from POST /accounts, for temp inbox only) ## Response Format All responses: { "success": bool, "data": ..., "error": "...", "errorCode": "..." } High-frequency temp inbox, auth, domain, balance, API key, permission, realtime auth, and rate-limit errors follow X-Locale, locale cookie, or Accept-Language when available. For stable integrations, prefer errorCode over localized error text. Users have a short numeric UID in addition to the hex ID. ## Rate Limiting - Anonymous (no auth): per-IP rate limit (configurable, default 2 rps) - API Key / JWT: per-user rate limit based on plan's max_rps (e.g. Free=10, Pro=60, Enterprise=200) - Burst: rps × burst_multiplier (configurable, default 10) - 429 responses include Retry-After header ## Endpoints ### Temporary Email POST /v1/accounts — Create temp inbox. Direct API calls require API key or Bearer JWT. Anonymous temp inbox creation without auth is reserved for the official YYDS Mail web app homepage. Body supports optional address/domain; API keys without domain auto-pick a random verified domain from the current domainScope, and signed-in homepage creation is counted as API usage. POST /v1/token — Get token for existing temp inbox GET /v1/accounts/me — Get current temp account info (temp token required) GET /v1/accounts/{id} — Get temp account by ID (temp token / API key / JWT) DELETE /v1/accounts/{id} — Deactivate temp inbox (temp token required) Note: Inbox responses include a "source" field ("web" or "api") indicating creation origin. Signed-in homepage temp inbox creation is returned as "api" so it lands in the user's API inbox group. ### Messages (temp token / API key / JWT) GET /v1/messages?address=xxx — List messages for an inbox (response shape: {messages,total}) GET /v1/messages/{id} — Get full message (text, html, attachments) PATCH /v1/messages/{id} — Mark message as read: {"seen":true} (API key requires write scope) DELETE /v1/messages/{id} — Delete a message (API key requires write scope) GET /v1/sources/{id} — Get raw email source wrapped in JSON (fields: id, data) ### Domains (public list is open, management needs auth) GET /v1/domains — List available domains (anonymous sees public only; auth also sees own verified private domains) GET /v1/me/domains — List my custom domains POST /v1/me/domains — Add domain: {"domain":"example.com"} (defaults to private; use PATCH to share publicly) DELETE /v1/me/domains/{id} — Delete domain PATCH /v1/me/domains/{id} — Toggle public/private: {"isPublic":true} GET /v1/me/domains/{id}/dns-guide — Get DNS setup instructions GET /v1/me/domains/{id}/dns-status — Check DNS verification status POST /v1/me/domains/{id}/verify — Trigger DNS verification ### API Keys (JWT / API key) GET /v1/me/api-keys — List my API keys POST /v1/me/api-keys — Create: {"name":"...","permissions":["read","write"],"domainScope":"all|public|own|specific","allowedDomainIds":["..."]} (specific domains must already be verified) DELETE /v1/me/api-keys/{id} — Revoke API key GET /v1/me/api-keys/{id}/usage — Get key usage statistics ### Webhooks (GET list: JWT / API key; all write operations: JWT only) GET /v1/me/webhooks — List my webhooks (API key OK for read) POST /v1/me/webhooks — Create: {"url":"https://...","events":["message.received"]} (JWT only). Supported events: message.received, message.deleted DELETE /v1/me/webhooks/{id} — Delete webhook (JWT only) PATCH /v1/me/webhooks/{id} — Update URL/events/active (JWT only) POST /v1/me/webhooks/{id}/test — Send test event, returns {success, statusCode, latencyMs} (JWT only) POST /v1/me/webhooks/{id}/regenerate-secret — Regenerate signing secret, shown once (JWT only) ### User Account (JWT / API key) GET /v1/me — Get profile + quota (includes uid) PATCH /v1/me — Update display name POST /v1/me/deactivate — Deactivate account (JWT only, body: {"confirmation":"DELETE MY ACCOUNT"}, 30-day cooling period, login to reactivate) GET /v1/me/quota — Get detailed quota usage (dimensions: domains, inboxes, apiKeys, apiCallsDaily, maxRps, bonusDaily, purchasedPool, totalPool; includes expiresAt RFC3339 when plan has expiration) GET /v1/me/inboxes — List my persistent inboxes POST /v1/me/inboxes — Create persistent inbox POST /v1/me/inboxes/{id}/claim — Claim a temp inbox as persistent DELETE /v1/me/inboxes/inactive — Batch delete all inactive API inboxes and purge their emails (returns {"deleted":N}) DELETE /v1/me/inboxes/{id} — Delete inbox ### Plans, Pricing & Public Stats GET /v1/pricing — Get pricing packages + currency config (public) GET /v1/plans — List active plans with quotas + max_rps GET /v1/stats — Platform statistics (totals, top domains, hourly activity, daily trend) ### Realtime GET /v1/auth/ws-ticket — Get short-lived WebSocket ticket (JWT / API key) WS /v1/ws?token={ticket} — Real-time inbox updates (use ticket from /auth/ws-ticket) ### Documentation Scope This llms.txt only lists the public integration surface. GET /v1/llms.txt — This file (AI-friendly API summary) Intentionally excluded from this public view: - /v1/admin/* - /v1/auth/register - /v1/auth/login - /v1/auth/oauth/* - /v1/auth/oauth/config - /v1/auth/token/* - /v1/auth/dev-login - /v1/health - /v1/metrics - /v1/announcements - /v1/me/domain-stats - /v1/me/redeem* - /v1/me/messages* - /v1/me/bind/* - /v1/me/balance* - /v1/me/credits - /v1/me/preferences - /v1/domain-reward/config - /v1/payment/create-order - /v1/payment/orders - /v1/payment/notify - /v1/payment/return - /v1/payment/balance-notify