Public

Activation API reference

Request/response documentation for each endpoint. Use the optional try-it panel when you want to hit your deployment from the browser.

Client login Home

Overview

Authentication

Every public endpoint requires query parameter token: your raw API key from the client panel. Invalid or missing tokens yield BAD_TOKEN.

Response format

Append type=JSON (default) or type=TEXT. JSON responses always use HTTP 200 with status either OK or ERROR; failures expose a string value code. TEXT mode returns plain body: success lines start with OK; errors use ERROR|CODE.

HTTP status

These routes typically return HTTP 200 for both success and business failures so clients can branch on status / TEXT prefix. The in-browser try-it helper may report proxied status separately.

Code Meaning
BAD_TOKEN Missing token, unknown key, or client record missing.

Endpoint-specific errors are listed under each operation below.

Interactive Optional: interactive try-it Toggle

Try endpoints here with your API token and optional parameters—responses match what you get when calling the API directly.

API base URL

Use this origin as the prefix for every endpoint listed on this page (same paths and query layout as classic Kopeechka-style APIs).

Example request base:

https://mailsapi.org

Account

GET user-balance

User balance

Returns the authenticated client’s current prepaid balance.

Query parameters

No endpoint-specific parameters besides global token and type.

Success (JSON)

Decimal balance as a string (six fractional digits typical).

{
    "status": "OK",
    "balance": "100.000000"
}

Success (TEXT)

Literal OK followed by balance, pipe-separated.

OK|100.000000

Errors (JSON value / TEXT after ERROR|)

No extra codes beyond BAD_TOKEN for typical inputs.

Interactive Run request (try-it) Toggle

No per-endpoint fields; token and type come from the panel above.

Mailbox

GET mailbox-get-email

Mailbox get email

Creates a new activation: allocates a disposable mailbox, debits balance, and returns its id and email. Incoming mail is matched until expiry.

Query parameters

Name Required Description
site yes Service/site key: hostname fragment only (http/https URLs are normalized to host). Must match mailbox-service pricing for your operator. One site per request — comma-separated multi-site values are not accepted.
mail_type no Legacy-compatible mode: ALL (default), DOMAINS, or empty → ALL.
regex no $REGEX — your PCRE pattern against the incoming message body so we extract only the matched fragment for you. Classic docs described multiple patterns separated by |,| when several sites were ordered in one site list; here there is exactly one site per order, so pass one pattern for this activation.
subject no $SUBJECT — optional substring the inbound subject must contain (case-insensitive).
clear no 1 = simplified local-part style for the generated mailbox; 0 or omit = default naming.
soft no $SOFT_ID — opaque string developers pass for referral programs / attribution; stored on the activation unchanged.

Plus global token and optional type.

Success (JSON)

New activation id and issued mailbox address.

{
    "status": "OK",
    "id": 42,
    "mail": "[email protected]"
}

Success (TEXT)

OK|id|mail

OK|42|[email protected]

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_SITE site missing or failed normalization.
BAD_DOMAIN mail_type invalid (not ALL / DOMAINS).
OUT_OF_STOCK No healthy domains available after blacklist filtering, or allocation exhausted.
BAD_BALANCE Insufficient balance for the resolved price.
SYSTEM_ERROR Reserved / unsupported client flags.
Interactive Run request (try-it) Toggle
GET mailbox-get-message

Mailbox get message

Returns extracted value (link/code/text) for a DONE activation, or a polling error while READY / waiting for inbound.

Query parameters

Name Required Description
id yes Activation id returned by mailbox-get-email.
full no 1 = append full stitched message in JSON fullmessage / TEXT block after separator.

Plus global token and optional type.

Success (JSON)

value holds extracted payload (regex match, URL/code heuristic, or truncated body). fullmessage present only when full=1.

{
    "status": "OK",
    "value": "https://example.com/verify?token=abc",
    "fullmessage": null
}

Success (TEXT)

With full=0: body is value. With full=1: value then separator ---- then fullmessage.

https://example.com/verify?token=abc

Errors (JSON value / TEXT after ERROR|)

Code When
NO_ACTIVATION Unknown id or not owned by this client.
WAIT_LINK Still READY, mail not matched yet, or inbound record missing.
ACTIVATION_CANCELED Activation was canceled.
Interactive Run request (try-it) Toggle
GET mailbox-cancel

Mailbox cancel

Cancels a READY activation and refunds its price. Not allowed after mail is matched (DONE) or for arbitrary terminal states.

Query parameters

Name Required Description
id yes Activation id to cancel.

Plus global token and optional type.

Success (JSON)

ok true when refund applied or activation already refunded by timeout.

{
    "status": "OK",
    "ok": true
}

Success (TEXT)

OK|1

OK|1

Errors (JSON value / TEXT after ERROR|)

Code When
NO_ACTIVATION Unknown id, wrong owner, or state not cancelable.
ACTIVATION_CANCELED Already canceled.
ACTIVATION_COMPLETE Mail already matched (DONE/HISTORY); refund not applicable.
Interactive Run request (try-it) Toggle
GET mailbox-reorder

Mailbox reorder

Issues a new activation reusing filters from the latest DONE activation for the same site + mailbox.

Query parameters

Name Required Description
site yes Service/site key (normalized).
email yes Mailbox address from a prior DONE activation.
regex no If set, replaces the prior activation’s $REGEX (same semantics as mailbox-get-email).
subject no If set, replaces the prior $SUBJECT filter.
soft no If set, replaces the prior $SOFT_ID.

Plus global token and optional type.

Success (JSON)

Same shape as mailbox-get-email on success.

{
    "status": "OK",
    "id": 43,
    "mail": "[email protected]"
}

Success (TEXT)

OK|id|mail

OK|43|[email protected]

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_SITE Invalid site or malformed email.
Activation not found No DONE activation with inbound match for site+email.
BAD_BALANCE Propagated from mailbox-get-email.
OUT_OF_STOCK Propagated from mailbox-get-email.
SYSTEM_ERROR Reserved / unsupported client flags.
Interactive Run request (try-it) Toggle
GET mailbox-get-fresh-id

Mailbox get fresh id

Returns the latest activation id for a site + mailbox among READY, DONE, or HISTORY.

Query parameters

Name Required Description
site yes Service/site key (normalized).
email yes Mailbox address.

Plus global token and optional type.

Success (JSON)

Latest matching activation id.

{
    "status": "OK",
    "id": 42
}

Success (TEXT)

OK|id

OK|42

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_SITE Invalid site or empty email.
NO_ACTIVATION No row for this client/site/email in READY/DONE/HISTORY.
Interactive Run request (try-it) Toggle
GET mailbox-set-comment

Mailbox set comment

Sets a plain-text comment on an activation (e.g. your internal job id).

Query parameters

Name Required Description
id yes Activation id.
comment yes Non-empty text; may be URL-encoded in the query string.

Plus global token and optional type.

Success (JSON)

ok true on update.

{
    "status": "OK",
    "ok": true
}

Success (TEXT)

OK|1

OK|1

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_COMMENT Missing or empty comment after decode/trim.
NO_ACTIVATION Unknown id or wrong owner.
Interactive Run request (try-it) Toggle
GET mailbox-get-bulk

Mailbox get bulk

Lists recent activations with URL-encoded value and comment fields for bulk export.

Query parameters

Name Required Description
count no 1–100, default 1.
email no Filter by mailbox address.
site no Filter by normalized site key.
comment no Exact comment match (URL-decoded).

Plus global token and optional type.

Success (JSON)

count and items: id, service, email, date (unix), status, value (URL-encoded link/extract), comment (URL-encoded).

{
    "status": "OK",
    "count": 1,
    "items": [
        {
            "id": 10,
            "service": "example.com",
            "email": "[email protected]",
            "date": 1715000000,
            "status": "DONE",
            "value": "https%3A%2F%2Fexample.com",
            "comment": ""
        }
    ]
}

Success (TEXT)

First line OK, second line count, then one pipe-separated row per item (id|service|email|date|status|value|comment).

OK
1
10|example.com|[email protected]|1715000000|DONE|https%253A%252F%252Fexample.com|

Errors (JSON value / TEXT after ERROR|)

No extra codes beyond BAD_TOKEN for typical inputs.

Interactive Run request (try-it) Toggle

Blacklist

GET domain-add-blacklist

Domain add blacklist

Adds or updates a per-client, per-site domain blacklist entry for issuance.

Query parameters

Name Required Description
site yes Service/site key (normalized).
domain yes Domain name to block; must belong to the operator’s domain pool.
expire no Optional unix expiry; 0 or omit for semantics defined by storage (see admin schema).

Plus global token and optional type.

Success (JSON)

ok true when upserted.

{
    "status": "OK",
    "ok": true
}

Success (TEXT)

OK|1

OK|1

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_SITE Invalid site.
BAD_DOMAIN Empty domain or not in allowed pool.
Interactive Run request (try-it) Toggle
GET domain-exclude-blacklist

Domain exclude blacklist

Removes a domain from the blacklist for site + client.

Query parameters

Name Required Description
site yes Service/site key (normalized).
domain yes Domain to remove.

Plus global token and optional type.

Success (JSON)

ok true when deleted.

{
    "status": "OK",
    "ok": true
}

Success (TEXT)

OK|1

OK|1

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_SITE Invalid site.
DOMAIN_NOT_IN_BLACK_LIST No matching blacklist row.
Interactive Run request (try-it) Toggle
GET blacklist-get-service

Blacklist get service

Lists blacklist rows for the client, optionally filtered by site.

Query parameters

Name Required Description
site no If provided, only rows for this normalized site.

Plus global token and optional type.

Success (JSON)

data is an array of { site, domain, expire } (expire string, 0 if unset).

{
    "status": "OK",
    "data": [
        {
            "site": "svc.test",
            "domain": "blocked.example",
            "expire": "0"
        }
    ]
}

Success (TEXT)

EMPTY if no rows; else lines site:domain:expire.

svc.test:blocked.example:0

Errors (JSON value / TEXT after ERROR|)

Code When
BAD_SITE site query present but invalid after normalization.
Interactive Run request (try-it) Toggle