# posta > API-first email hosting for developers and AI agents: connect your own domain, then create real IMAP/SMTP mailboxes with one API call (POST /v1/mailboxes → address, IMAP and SMTP credentials). Free early access is open: 1 domain, 1 mailbox, 500 MB, up to 50 outgoing messages a day per mailbox. No card, no payment. ## What it is - Real mailboxes, not a sending-only API: each mailbox has IMAP and SMTP access, so an agent or a service can both receive and send mail. - Domain-based: you connect a domain you control; mailboxes are created under it from code. - Built for automation: designed for developers and for the AI agents they run (sign-ups, verification mail, inbound processing). ## How to start 1. Create a free account: https://posta.preved.co/app/register/ (confirm your email). 2. Add your domain in the dashboard; set the DNS records it shows (ownership TXT, MX mail.posta.preved.co, SPF include:spf.posta.preved.co, DKIM, DMARC). 3. Create a mailbox from the dashboard or the API. Clients connect to mail.posta.preved.co: IMAP 993 (SSL), SMTP 587 (STARTTLS) or 465 (SSL); username is the full address. ## Pages - [Home (English)](https://posta.preved.co/): what posta is, how it works, sign-up. - [Ana sayfa (Türkçe)](https://posta.preved.co/tr/): aynı içeriğin Türkçesi. - [API documentation](https://posta.preved.co/docs): quickstart with curl, Python, Node; endpoints, errors. - [posta vs AgentMail](https://posta.preved.co/compare/agentmail): factual comparison (hosting, pricing, licence, tooling). - [OpenAPI spec](https://posta.preved.co/openapi.json) · [Full text for LLMs](https://posta.preved.co/llms-full.txt) - [Privacy](https://posta.preved.co/privacy) · [Terms of Service](https://posta.preved.co/terms) · [Acceptable Use](https://posta.preved.co/aup) · [Sales terms and refunds](https://posta.preved.co/sales) (versioned copies at /terms/2026-10-08-2 etc.) ## Status Free early access (8 October 2026). Paid plan: Pro, 1 domain and 10 mailboxes for a flat $100 a year, paid online by card (iyzico), no automatic renewal, 14-day full refund. Bulk and marketing mail is not allowed. Delivery to Outlook/Hotmail addresses may currently be rejected. ## About posta is a PREVED service, operated by HEYVANKA YAZILIM LTD. ŞTİ. (Türkiye). PREVED (https://preved.co) is the provider of HeyvAql (https://heyvaql.com), posta (this site) and PREVED Creator (https://creator.preved.co). ## Contact merhaba@preved.co · abuse: abuse@preved.co · legal: legal@preved.co · personal data: privacy@preved.co --- # Full API documentation (same as https://posta.preved.co/docs) posta API documentation posta is a mailbox API: programmable mailbox hosting. Connect a domain you control, then create real IMAP/SMTP mailboxes with one API call. It is built for developers and AI agents that need to both receive and send mail. Machine-readable: /openapi.json, /llms.txt, /llms-full.txt. Quickstart (5 minutes) - Create a free account and confirm your email. Free early access: 1 domain, 1 mailbox, 500 MB, up to 50 outgoing messages a day per mailbox. - In the dashboard, create an API key (scopes: domains:read, domains:write, mailboxes:read, mailboxes:write). The key (pk_live_…) is shown once. Keys can only be created in the dashboard, not with another key. - Add a domain, publish the DNS records it returns, verify, then create a mailbox: # 1. Add a domain (needs a key with domains:write) curl -s https://posta.preved.co/v1/domains \ -H "Authorization: Bearer $POSTA_KEY" -H "Content-Type: application/json" \ -d '{"name": "example.com"}' # → 201 {"id": 7, "status": "pending", "dns": {"ownership_txt": ..., "mx": ..., "dkim": null}, ...} (DKIM key is generated at verification) # 2. Publish the DNS records from the response, then ask posta to check them curl -s -X POST https://posta.preved.co/v1/domains/7/verify -H "Authorization: Bearer $POSTA_KEY" # → {"status": "verified", ...} once DNS has propagated. Then GET /v1/domains/7 returns the DKIM TXT record to publish. # 3. Create a mailbox (needs mailboxes:write; you choose the password) curl -s https://posta.preved.co/v1/mailboxes \ -H "Authorization: Bearer $POSTA_KEY" -H "Content-Type: application/json" \ -d '{"domain_id": 7, "local_part": "agent", "password": "a-long-random-passphrase"}' # → 201 {"id": 12, "address": "agent@example.com", "quota_mb": 500, "status": ..., "created_at": ...} Authentication Send Authorization: Bearer pk_live_… on every request. Each endpoint requires a scope; a missing scope returns an error. Base URL: https://posta.preved.co/v1. Errors have one shape: {"error": {"code": "…", "message": "…"}}. Endpoints - GET /v1/domains, POST /v1/domains {"name"} · scopes domains:read / domains:write - GET /v1/domains/{id}, DELETE /v1/domains/{id} - POST /v1/domains/{id}/verify: checks DNS and returns the domain with status - GET /v1/mailboxes, POST /v1/mailboxes {"domain_id","local_part","password"} · mailboxes:read / mailboxes:write - DELETE /v1/mailboxes/{id} - GET /v1/usage: plan, limits and current usage · domains:read Python import os, requests API = "https://posta.preved.co/v1" H = {"Authorization": f"Bearer {os.environ['POSTA_KEY']}"} domain = requests.post(f"{API}/domains", headers=H, json={"name": "example.com"}).json() # publish domain["dns"] records at your DNS provider, then: requests.post(f"{API}/domains/{domain['id']}/verify", headers=H).raise_for_status() box = requests.post(f"{API}/mailboxes", headers=H, json={ "domain_id": domain["id"], "local_part": "agent", "password": "a-long-random-passphrase"}).json() print(box["address"]) Node.js const API = "https://posta.preved.co/v1"; const H = { Authorization: `Bearer ${process.env.POSTA_KEY}`, "Content-Type": "application/json" }; const domain = await (await fetch(`${API}/domains`, { method: "POST", headers: H, body: JSON.stringify({ name: "example.com" }) })).json(); // publish domain.dns records at your DNS provider, then: await fetch(`${API}/domains/${domain.id}/verify`, { method: "POST", headers: H }); const box = await (await fetch(`${API}/mailboxes`, { method: "POST", headers: H, body: JSON.stringify({ domain_id: domain.id, local_part: "agent", password: "a-long-random-passphrase" }) })).json(); console.log(box.address); Use the mailbox (IMAP and SMTP) Connect to mail.posta.preved.co. IMAP: port 993 (SSL). SMTP: port 587 (STARTTLS) or 465 (SSL). The username is the full address; the password is the one you set when creating the mailbox. import imaplib, smtplib from email.message import EmailMessage # Receive imap = imaplib.IMAP4_SSL("mail.posta.preved.co", 993) imap.login("agent@example.com", PASSWORD) imap.select("INBOX") status, data = imap.search(None, "UNSEEN") # Send msg = EmailMessage(); msg["From"] = "agent@example.com"; msg["To"] = "you@example.net" msg["Subject"] = "Hello"; msg.set_content("Sent from a posta mailbox.") with smtplib.SMTP("mail.posta.preved.co", 587) as s: s.starttls(); s.login("agent@example.com", PASSWORD); s.send_message(msg) DNS records for a domain Publish the records returned by the API. Required for verification: the ownership TXT (name _posta-verify., value posta-verify=…) and MX 10 mail.posta.preved.co. Recommended for sending reputation: SPF include:spf.posta.preved.co, the DKIM TXT (returned in dns.dkim after verification), and a DMARC record (_dmarc TXT, e.g. v=DMARC1; p=none). Errors - invalid_local_part (HTTP 400): Mailbox name not allowed (reserved names like postmaster, admin, abuse, noreply are blocked). - weak_password (HTTP 400): Password rejected by the password policy. - domain_not_verified (HTTP 403): Verify the domain before creating mailboxes. - plan_limit (HTTP 403): Plan limit reached (free: 1 domain, 1 mailbox, 500 MB, up to 50 outgoing messages a day). - mailbox_exists (HTTP 409): That address already exists. - not_found (HTTP 404): Resource does not exist or is not yours. - backend_error (HTTP 503): Mail backend temporarily unavailable; retry shortly. Limits and rules Free early access: 1 domain, 1 mailbox, 500 MB, up to 50 outgoing messages a day. Bulk and marketing mail is not allowed (acceptable use). Delivery to Outlook/Hotmail addresses may currently be rejected. Terms: /terms, privacy: /privacy. # OpenAPI {"openapi": "3.0.3", "info": {"title": "posta mailbox API", "version": "1.0.0", "description": "Programmable mailbox hosting: connect a domain, create real IMAP/SMTP mailboxes with one call. Free early access: 1 domain, 1 mailbox, 500 MB, up to 50 outgoing messages a day per mailbox. Mailbox access: mail.posta.preved.co IMAP 993 (SSL), SMTP 587 (STARTTLS) / 465 (SSL).", "contact": {"email": "merhaba@preved.co"}, "termsOfService": "https://posta.preved.co/terms"}, "servers": [{"url": "https://posta.preved.co/v1"}], "security": [{"bearer": []}], "paths": {"/domains": {"get": {"summary": "List domains", "operationId": "listDomains", "x-scope": "domains:read", "responses": {"200": {"description": "Domains", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/Domain"}}}}}, "401": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}, "post": {"summary": "Add a domain", "operationId": "addDomain", "x-scope": "domains:write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string", "example": "example.com"}}}}}}, "responses": {"201": {"description": "Created; publish the returned DNS records", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Domain"}}}}, "400": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}, "403": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}}, "/domains/{id}": {"get": {"summary": "Get a domain", "operationId": "getDomain", "x-scope": "domains:read", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Domain", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Domain"}}}}, "404": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}, "delete": {"summary": "Delete a domain", "operationId": "deleteDomain", "x-scope": "domains:write", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"204": {"description": "Deleted"}, "404": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}}, "/domains/{id}/verify": {"post": {"summary": "Check DNS and verify the domain", "operationId": "verifyDomain", "x-scope": "domains:write", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Domain with current status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Domain"}}}}, "404": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}}, "/mailboxes": {"get": {"summary": "List mailboxes", "operationId": "listMailboxes", "x-scope": "mailboxes:read", "responses": {"200": {"description": "Mailboxes", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/Mailbox"}}}}}}}, "post": {"summary": "Create a mailbox on a verified domain", "operationId": "createMailbox", "x-scope": "mailboxes:write", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["domain_id", "local_part", "password"], "properties": {"domain_id": {"type": "integer"}, "local_part": {"type": "string", "example": "agent"}, "password": {"type": "string", "description": "Chosen by you; used for IMAP/SMTP login."}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Mailbox"}}}}, "400": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}, "403": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}, "409": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}, "503": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}}, "/mailboxes/{id}": {"delete": {"summary": "Delete a mailbox", "operationId": "deleteMailbox", "x-scope": "mailboxes:write", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"204": {"description": "Deleted"}, "404": {"description": "Error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}}}}}, "/usage": {"get": {"summary": "Plan, limits and usage", "operationId": "getUsage", "x-scope": "domains:read", "responses": {"200": {"description": "Usage", "content": {"application/json": {"schema": {"type": "object"}}}}}}}}, "components": {"securitySchemes": {"bearer": {"type": "http", "scheme": "bearer", "description": "API key (pk_live_\u2026) created in the dashboard."}}, "schemas": {"Domain": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "status": {"type": "string"}, "verified_at": {"type": "string", "nullable": true}, "created_at": {"type": "string"}, "dns": {"type": "object", "description": "ownership_txt, mx, dkim records to publish"}, "last_check": {"nullable": true}, "last_check_at": {"type": "string", "nullable": true}}}, "Mailbox": {"type": "object", "properties": {"id": {"type": "integer"}, "address": {"type": "string"}, "quota_mb": {"type": "integer"}, "status": {"type": "string"}, "created_at": {"type": "string"}}}}}}