API documentation

Base URL for all requests:

https://api.smakmail.com/api/v1

Exact request and response schemas are available in OpenAPI. Start by checking your token with GET /me.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  https://api.smakmail.com/api/v1/me

Protected methods use a Bearer token. Methods that read a specific mailbox or its messages also require the current password of that mailbox.

Authorization: Bearer <API_TOKEN>
X-Mailbox-Password: <MAILBOX_PASSWORD>

Do not pass the API token or mailbox password in the query string. Orders, mailboxes, and messages are restricted to the current user.

• Standard API: 10 requests/second, burst 20.
• Developer: 50 requests/second, burst 250.
• Developer: 5,000,000 requests per day.
• Developer: 100,000,000 requests per 30 days.
• Developer: 199 RUB for 30 days. Personal API low-qty 1–99: RUB 0.08/mailbox with Developer and RUB 0.80/mailbox without it. For other supported products, a 1-item API order with Developer uses the 1,000-tier unit price. One-time trial: 72 hours with no automatic charge.

Rate-limit exhaustion returns HTTP 429 rate_limited. Developer quota exhaustion returns HTTP 429 quota_exceeded. GET /developer also returns the currently effective limits.

GET  /api/v1/me
GET  /api/v1/balance
GET  /api/v1/products

GET  /api/v1/developer
POST /api/v1/developer/trial
POST /api/v1/developer/subscribe

GET  /api/v1/shop/domain-options

POST /api/v1/orders/quote
POST /api/v1/orders
GET  /api/v1/orders/{order_id}
GET  /api/v1/orders/{order_id}/result

GET  /api/v1/mailbox
GET  /api/v1/mailbox/messages
GET  /api/v1/mailbox/latest-code
POST /api/v1/mailbox/password/change

GET  /api/v1/messages/{msg_id}
GET  /api/v1/messages/{msg_id}/extract
GET  /api/v1/messages/{msg_id}/html

GET    /api/v1/webhooks
POST   /api/v1/webhooks
GET    /api/v1/webhooks/{webhook_id}
DELETE /api/v1/webhooks/{webhook_id}
GET    /api/v1/webhooks/{webhook_id}/deliveries
GET    /api/v1/webhooks/{webhook_id}/mailboxes
POST   /api/v1/webhooks/{webhook_id}/mailboxes
DELETE /api/v1/webhooks/{webhook_id}/mailboxes/{email}
POST   /api/v1/webhooks/{webhook_id}/test

OpenAPI is the canonical schema for parameters and responses of these methods.

Read the current catalog from GET /products before ordering. For low-qty 1–99, call POST /orders/quote first: it does not create an order or charge the balance, and returns the unit price, total price, and Developer comparison. POST /orders creates the order and immediately charges the balance when the order succeeds. POST /orders requires a unique Idempotency-Key. Personal API low-qty 1–99 costs RUB 0.80/mailbox without Developer and RUB 0.08/mailbox with Developer. For other supported products, a 1-item API order with Developer uses the 1,000-tier unit price. Personal uses the domain field. Pool products support domain_selection with mode only or exclude.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"product":"Eternal","qty":1}' \
  https://api.smakmail.com/api/v1/orders/quote

POST /orders/quote is pricing-only: it does not create an order, does not charge the balance, and does not require an Idempotency-Key. After checking the price, send a separate POST /orders only when you want to make the purchase.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-001" \
  -d '{"product":"Eternal","qty":100}' \
  https://api.smakmail.com/api/v1/orders

Order status: GET /orders/{order_id}. Completed order result: GET /orders/{order_id}/result.

Reading a mailbox, message list, message card, HTML, extract, or latest-code requires X-Mailbox-Password with the current password of that mailbox.

curl -sS \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "X-Mailbox-Password: <MAILBOX_PASSWORD>" \
  --get \
  --data-urlencode "email=mailbox@example.com" \
  https://api.smakmail.com/api/v1/mailbox/latest-code

GET /mailbox/latest-code is the simplest option when an automation only needs the latest extracted code. GET /messages/{msg_id}/extract returns extracted codes and links.

The API supports webhook endpoints and bindings for specific mailboxes. Mailbox passwords are used only to verify access when creating a binding and are not stored.

GET    /api/v1/webhooks
POST   /api/v1/webhooks
GET    /api/v1/webhooks/{webhook_id}
DELETE /api/v1/webhooks/{webhook_id}
GET    /api/v1/webhooks/{webhook_id}/deliveries
GET    /api/v1/webhooks/{webhook_id}/mailboxes
POST   /api/v1/webhooks/{webhook_id}/mailboxes
DELETE /api/v1/webhooks/{webhook_id}/mailboxes/{email}
POST   /api/v1/webhooks/{webhook_id}/test

bad_request
invalid_token
forbidden
not_found
conflict
validation_error
rate_limited
quota_exceeded
mailbox_password_required
invalid_mailbox_password
internal_error

Errors are returned as JSON with ok=false, error.code, error.message, and request_id.

• OpenAPI
• IMAP
• POP3
• Service status
• Acceptable use and service terms