Agentyk API
Email for AI Agents — REST API Reference
Quick Start
# 1. Register
curl -X POST https://agentyk.ru/register \
-H "Content-Type: application/json" \
-d '{"username":"myagent"}'
# Response: {email, temp_password, api_key, recovery_seed, invoice_id, btc_wallet, amount_btc}
# 2. Activate with coupon (or pay BTC to btc_wallet)
curl -X POST https://agentyk.ru/register/redeem \
-H "Content-Type: application/json" \
-d '{"invoice_id":"INV-xxx","coupon":"AYK-XXXX-XXXX-XXXX"}'
# 3. Send email
curl -X POST https://agentyk.ru/mail/send \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"to":"someone@example.com","subject":"Hello","body":"Hi from my agent"}'
# 4. Read inbox
curl https://agentyk.ru/mail -H "X-API-Key: your-api-key"
Authentication
Two authentication methods depending on endpoint group:
| Method | Used for | How |
|---|
| API Key | /mail/* and /account/* | X-API-Key header |
| Email + Password | /login/* management | JSON body: {"email":"...","password":"..."} |
Registration
POST/register
Create a new email account
Body: {"username": "desired-name"}
Returns: email, temp_password, api_key, recovery_seed (12 words), invoice_id, btc_wallet, amount_btc
GET/register/status/:invoice_id
Check payment status
Returns: {"status": "pending_payment | settled"}
POST/register/redeem
Activate account with coupon code
Body: {"invoice_id": "...", "coupon": "AYK-XXXX-XXXX-XXXX"}
Username rules: 3-32 characters, lowercase alphanumeric, dots, hyphens. Must start and end with letter or number.
Important: Save your recovery_seed immediately. It is shown only once at registration and cannot be retrieved later.
Payment
$60 USD/year, payable in Bitcoin or coupon.
Option A: Bitcoin
Send the exact amount_btc to the btc_wallet address returned at registration. Monitor with GET /register/status/:invoice_id until status is settled.
Option B: Coupon
POST /register/redeem with the invoice ID and coupon code. Instant activation.
24h hold: The email address is reserved for 24 hours pending payment. If no payment is received, the address is recycled.
Email API
All endpoints require X-API-Key header.X-API-Key
GET/mailAPI Key
List messages in mailbox
Query params (all optional, combinable): folder, search, from, to, subject, since, before
Returns: [{id, from, to, subject, date, size}]
GET/mail/:idAPI Key
Read a single message
Returns: {id, from, to, subject, body, date, attachments: [{blobId, filename, type, size}]}
GET/mail/attachment/:blobIdAPI Key
Download attachment (raw binary)
Use blobId from the message attachments array
DELETE/mail/:idAPI Key
Delete a message
POST/mail/sendAPI Key
Send an email
Body: {"to":"recipient@example.com", "subject":"...", "body":"...", "attachments":[{"filename":"file.pdf", "content":"base64...", "type":"application/pdf"}]}
Attachments are optional. Content is base64-encoded.
Account Management
GET/account/statusAPI Key
Get account info
Returns: email, status, expires_at, quota_used, created_at
POST/account/change-passwordAPI Key
Change password (via API key)
Body: {"new_password": "min 8 chars, 1 uppercase, 1 number, 1 special"}
Login-based Management
These require email and password in the JSON body.email+password
POST/loginemail+pw
Login / get account details
Returns: email, username, status, api_key, expires_at, recovery_email, forward_email
POST/login/change-passwordemail+pw
Change password
Additional: "new_password"
POST/login/recovery-emailemail+pw
Set recovery email for password resets
Additional: "recovery_email"
POST/login/forwardemail+pw
Forward all incoming mail to another address
Additional: "forward_email" (empty string to disable)
POST/login/extendemail+pw
Get BTC payment info for renewal
Returns: invoice_id, btc_wallet, amount_btc
POST/login/extend/redeememail+pw
Extend account with coupon
Additional: "coupon": "AYK-XXXX-XXXX-XXXX"
POST/login/deleteemail+pw
Permanently delete account and all data
Additional: "confirm": "DELETE" — irreversible
Sender Whitelist
Protect against email prompt injection. When enabled, only mail from whitelisted senders reaches your mailbox — all others are rejected at SMTP level.
GET/account/whitelistAPI Key
Get current whitelist config
Returns: {enabled: bool, emails: [...]}
POST/account/whitelistAPI Key
Set sender whitelist
Body: {"enabled": true, "emails": ["operator@company.com", "*@trusted-domain.com"]}
Supports exact addresses (user@domain.com) and domain wildcards (*@domain.com).
Password Reset & Recovery
POST/login/request-reset
Send reset link to recovery email
Body: {"email": "your@agentyk.ru"}
POST/login/reset
Reset password with token from email
Body: {"token": "...", "new_password": "..."}
POST/login/recover/seed
Reset password using 12-word recovery seed from registration
Body: {"email": "...", "seed": "word1 word2 ... word12", "new_password": "..."}
POST/login/recover/invoice
Reset password by proving ownership via payment invoice
Body: {"email": "...", "invoice_id": "any payment invoice ID", "new_password": "..."}
Account Lifecycle
| Timeline | Status | Send | Receive | API |
|---|
| Active | active | Yes | Yes | Full access |
| -30 days | active | Yes | Yes | Full + renewal reminder |
| Expiry (0) | expired | No | Yes | Read-only |
| +30 days | suspended | No | No | Blocked + deletion warning |
| +60 days | deleted | — | — | Permanently deleted |
Renewal via POST /login/extend or /login/extend/redeem at any stage before deletion restores full access.
Server Details
| Service | Details |
|---|
| IMAP | mail.agentyk.ru:993 (implicit TLS) |
| SMTP | mail.agentyk.ru:465 (implicit TLS) |
| Quota | 500 MB (oldest messages auto-pruned when full) |
| Price | $60 USD/year (Bitcoin or coupon) |
| Health | GET /health → {"status":"ok"} |
| Machine spec | /.well-known/agent.json |
Rules: Zero tolerance for spam. Do not use for mass mailing, phishing, or abuse. Accounts violating these rules will be terminated without refund.