1. Overview
SmakMail API v1 is the public product API for mailbox ordering, mailbox access, incoming messages, extracted codes and links, Developer status, and webhooks.
The API is for incoming-mail workflows. It does not provide SMTP sending or administrative access.
2. Base URL
https://api.smakmail.com/api/v1
Machine-readable schema:
GET https://api.smakmail.com/api/v1/openapi.json
3. Authentication
Protected requests use a Bearer API token:
Authorization: Bearer <API_TOKEN>
Mailbox-level access
Reading a mailbox or its messages also requires the current mailbox password:
X-Mailbox-Password: <MAILBOX_PASSWORD>
Do not put the API token or mailbox password in query parameters.
4. Rate limits and quotas
- Standard API: 10 requests/second, burst 20.
- Developer: 50 requests/second, burst 250.
- Developer daily quota: 5,000,000 requests.
- Developer rolling 30-day quota: 100,000,000 requests.
The API exposes limit information in response headers:
X-RateLimit-Limit X-RateLimit-Burst X-RateLimit-Remaining X-RateLimit-Policy X-Quota-Day-Remaining X-Quota-30D-Remaining
Rate-limit exhaustion returns HTTP 429 with rate_limited. Developer quota exhaustion returns HTTP 429 with quota_exceeded.
5. Main endpoints
GET /me
GET /balance
GET /products
GET /developer
POST /developer/trial
POST /developer/subscribe
GET /shop/domain-options
POST /orders
GET /orders/{order_id}
GET /orders/{order_id}/result
GET /mailbox
GET /mailbox/messages
GET /mailbox/latest-code
POST /mailbox/password/change
GET /messages/{msg_id}
GET /messages/{msg_id}/extract
GET /messages/{msg_id}/html
GET /webhooks
POST /webhooks
GET /webhooks/{webhook_id}
DELETE /webhooks/{webhook_id}
GET /webhooks/{webhook_id}/deliveries
GET /webhooks/{webhook_id}/mailboxes
POST /webhooks/{webhook_id}/mailboxes
DELETE /webhooks/{webhook_id}/mailboxes/{email}
POST /webhooks/{webhook_id}/testRequest and response schemas are available in the public OpenAPI document.
6. Read-only examples
Check the token
curl -sS \ -H "Authorization: Bearer <TOKEN>" \ https://api.smakmail.com/api/v1/me
Balance
curl -sS \ -H "Authorization: Bearer <TOKEN>" \ https://api.smakmail.com/api/v1/balance
Products
curl -sS \ -H "Authorization: Bearer <TOKEN>" \ https://api.smakmail.com/api/v1/products
Developer status and effective limits
curl -sS \ -H "Authorization: Bearer <TOKEN>" \ https://api.smakmail.com/api/v1/developer
Mailbox messages
curl -sS \ -H "Authorization: Bearer <TOKEN>" \ -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \ --get \ --data-urlencode "email=mailbox@example.com" \ --data-urlencode "limit=5" \ https://api.smakmail.com/api/v1/mailbox/messages
7. Creating an order
Order creation requires a unique Idempotency-Key. Current availability and product information should be read from GET /products.
curl -sS \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: example-order-1" \
-d '{"product":"Eternal","qty":100}' \
https://api.smakmail.com/api/v1/orders8. Error contract
bad_request invalid_token forbidden not_found conflict validation_error rate_limited quota_exceeded mailbox_password_required invalid_mailbox_password internal_error
Errors use the following envelope:
{
"ok": false,
"error": {
"code": "invalid_token",
"message": "Bearer token is invalid"
},
"request_id": "..."
}9. Related protocols and operational links
10. Changelog
- 2026-08-13: documented current Standard and Developer API limits, published POP3 documentation, and aligned public technical documentation discovery.
- 2026-06-24: public API and IMAP documentation published on smakmail.com.