# YYDS Mail API
> Public integration summary for developers and AI assistants.
> Base URL: https://maliapi.215.im/v1

## Public Scope
This llms.txt follows the same public integration surface shown in /docs:
- Quick Start
- Temporary Email
- Messages
- Webhooks
- AI / LLM
- Error Handling

Additional public query endpoints:
- GET /v1/domains
- GET /v1/plans
- GET /v1/pricing
- GET /v1/domain-reward/config
- GET /v1/stats

## Authentication
- Bearer JWT: Authorization: Bearer <access_token>
- API Key: X-API-Key: AC-xxxxxx
- Temp Token: Authorization: Bearer <temp_token>

## Notes
- Temp tokens are only valid for temporary inbox flows such as /v1/accounts/me, /v1/accounts/{id}, /v1/messages*, and /v1/sources/{id}
- Anonymous temp inbox creation is only available through the official YYDS Mail homepage bridge
- Signed-in owner endpoints under /v1/me/domains*, /v1/me/wildcard-rules*, and /v1/me/dns-service-connections* require Bearer JWT; X-API-Key cannot manage those resources
- Signed-in domain management uses those owner endpoints for DNS status refresh, DNS verification, wildcard rule creation/pause, DNS automation settings, and provider-backed DNS sync
- DNS automation is optional. Without a service connection, the standard custom-domain flow remains manual TXT + MX setup
- The first DNS automation connector is Cloudflare. Configure it from the signed-in domain management page, then create a token with Zone:Read + DNS:Edit and include the domains you want to manage in the token scope
- Current live rate-limit summary before verified-domain bonus: VIP=25 req/s, Plus=35 req/s, Max=55 req/s, Neo=120 req/s
- Burst multiplier: 3

## Quick Start
1. Sign in at /login
2. Create an API key from the dashboard
3. Call the API with X-API-Key or Bearer JWT

## Temporary Email
POST   /v1/accounts                    — Create a temporary inbox
POST   /v1/accounts/wildcard           — Force wildcard child-domain creation
Rules for POST /v1/accounts:
- Pass domain to create under a real domain
- Pass subdomain together with domain to create under a wildcard child domain
- localPart is the preferred request field; the legacy address field is still accepted
- POST /v1/accounts keeps fixed-domain behavior when subdomain is omitted
- POST /v1/accounts/wildcard forces wildcard mode and will use the key default or a random child domain when possible

Example with normal domain:
{ "localPart": "my-prefix", "domain": "public.example.com" }

Example with automatic child domain:
{ "localPart": "my-prefix", "domain": "public.example.com" }

Example with fixed child domain:
{ "localPart": "my-prefix", "domain": "public.example.com", "subdomain": "team-a" }

POST   /v1/token                       — Refresh the temp token for the same active inbox
GET    /v1/accounts/me                 — Get the current temp inbox profile
GET    /v1/accounts/{id}               — Get temp inbox detail by ID
DELETE /v1/accounts/{id}               — Deactivate a temporary inbox

## Messages
GET    /v1/messages?address=xxx        — List messages for an inbox
POST   /v1/messages/mark-read          — Mark the current mailbox as read
GET    /v1/messages/{id}?address=xxx   — Get full message detail
PATCH  /v1/messages/{id}?address=xxx   — Update message state such as seen=true
DELETE /v1/messages/{id}?address=xxx   — Delete a message
GET    /v1/sources/{id}?address=xxx    — Get raw message source wrapped in JSON

## Webhooks
GET    /v1/me/webhooks                 — List webhook subscriptions
POST   /v1/me/webhooks                 — Create a webhook subscription
PATCH  /v1/me/webhooks/{id}            — Update a webhook
DELETE /v1/me/webhooks/{id}            — Delete a webhook
POST   /v1/me/webhooks/{id}/test       — Send a test event
POST   /v1/me/webhooks/{id}/regenerate-secret — Regenerate the webhook signing secret

## AI / LLM
GET    /v1/llms.txt                    — This AI-friendly public API summary

## Error Handling
All errors follow the same envelope:
{ "success": false, "error": "...", "errorCode": "..." }

Prefer errorCode over localized error text in stable integrations.
429 responses include Retry-After.

## Intentionally Excluded
Admin, balance, domain-governance, and other signed-in console routes are intentionally excluded from this public llms surface. Signed-in domain onboarding, wildcard rule management, and DNS automation stay inside the dashboard rather than the public integration contract.