LoftBox दस्तावेज़ — AI एजेंट्स के लिए ईमेल API

शुरुआत

शुरुआत करना

LoftBox पर्सनल बीटा एक owner email से शुरू होता है। साइनअप संगठन बनाता है और एक 6-अंकीय सत्यापन टोकन ईमेल करता है। केवल owner-email सत्यापन के बाद ही LoftBox पहली API key लौटाता है, और वह plaintext key एक बार दिखाई जाती है। सत्यापन owner को बीटा सीमाओं और भविष्य के admin/billing साइनअप पथ के साथ एक स्वागत ईमेल भी भेजता है।

पर्सनल बीटा खाते प्रतिदिन 100 outbound भेजने तक सीमित हैं। मेलबॉक्स संदेश रिटेंशन डिफ़ॉल्ट रूप से 7 दिन है। एंटरप्राइज ऑनबोर्डिंग, बिलिंग, संगठन सदस्यता, और बड़ी सीमाएँ रोडमैप आइटम हैं।

POST /v1/auth/signupएक पर्सनल बीटा संगठन बनाएं और owner-email सत्यापन टोकन भेजें।
POST /v1/auth/signup/verifyowner email सत्यापित करें, प्रारंभिक API key एक बार प्राप्त करें, और owner स्वागत सूचना ट्रिगर करें।
POST /v1/agentsowner, उद्देश्य, और policy scope के साथ एक एजेंट पहचान बनाएं।
POST /v1/domainsअपने नियंत्रण वाले किसी डोमेन के लिए custom-domain ऑनबोर्डिंग शुरू करें।
POST /v1/agents/{agent_id}/mailboxesएक LoftBox-managed बीटा मेलबॉक्स या सत्यापित custom-domain मेलबॉक्स बनाएं।
POST /v1/messagesएजेंट मेलबॉक्स से ऑपरेशनल ईमेल भेजें।
GET /v1/mailboxes/{id}/inboxजब एजेंट के पास कोई webhook endpoint न हो तो unacknowledged inbound संदेशों को poll करें।
POST /v1/messages/{id}/agent-receiptsRecord whether the agent saw, processed, failed, or ignored an inbound message.
GET /v1/messages/{id}/agent-statusRead the operator-facing status that combines LoftBox state, inbox ack, webhook delivery, and the latest agent receipt.

तुरंत शुरू करें

स्व-साइनअप — तुरंत API कुंजी

POST /v1/auth/agent-signup पर एक बिना-प्रमाणीकरण वाले कॉल से कार्यशील API कुंजी प्राप्त करें। कंसोल साइनअप की आवश्यकता नहीं है, इसलिए एजेंट तुरंत शुरू कर सकता है।

जब तक स्वामी ईमेल द्वारा खाते को सत्यापित (दावा) नहीं करता, एजेंट केवल उसी एक स्वामी पते के साथ भेज और प्राप्त कर सकता है — एक बंद लूप। स्वामी loftbox.net/claim पर (लिंक स्वचालित रूप से ईमेल किया जाता है) या दावा API के माध्यम से दावा करता है, जिससे प्रतिबंध हट जाता है। बिना दावे वाले खाते 30 दिनों के बाद हटा दिए जाते हैं।

curl -X POST https://api.loftbox.net/v1/auth/agent-signup \
  -H 'content-type: application/json' \
  -d '{"owner_email":"[email protected]"}'
# -> { "api_key": "lb_live_...", "mailbox_address": "[email protected]",
#      "signup_status": "unverified" }

POST /v1/auth/agent-signupतुरंत एक प्रतिबंधित (असत्यापित) खाता बनाता है और एक बार API कुंजी लौटाता है।
POST /v1/auth/claim/startदावा शुरू करने के लिए स्वामी पते पर एक सत्यापन कोड भेजता है।
POST /v1/auth/claim/verifyखाते को सत्यापित में बढ़ाने और प्रतिबंधित मोड हटाने के लिए कोड सत्यापित करता है।

Endpoint

Base URL और मशीन-रीडेबल डॉक्स

विहित सार्वजनिक API endpoint है https://api.loftbox.net। होमपेज एक /api/* प्रॉक्सी पथ प्रीव्यू सत्यापन के लिए रखता है, लेकिन प्रोडक्शन इंटीग्रेशन को समर्पित API hostname का उपयोग करना चाहिए।

export BASE_URL="https://api.loftbox.net"
export LOFTBOX_API_KEY="lb_live_replace_me"

इंटीग्रेशन वायर करने से पहले edge और schema जाँचें:

curl -i "$BASE_URL/health"
curl -i "$BASE_URL/openapi.json"
curl -i "$BASE_URL/llms.txt"

यह https://loftbox.net/api route /api prefix को हटाता है और उसी Fly API origin पर अग्रेषित करता है। इसे Pages प्रीव्यू जाँच के लिए उपयोग करें, प्राथमिक इंटीग्रेशन URL के रूप में नहीं।

Client libraries

Official SDKs

Official client libraries wrap the REST API in idiomatic, typed clients across eight languages — with popular framework integrations. Every SDK uses the same API key, the same approval/rate-limit/audit pipeline, and exposes the inbound safety signals: the prompt-injection score on inbound messages and the sender allow/block rules.

Language	Install	Framework
Python	`pip install loftbox`	LangChain, CrewAI
TypeScript / JS	`npm i @loftbox/sdk`	MCP
Go	`go get github.com/TheMagicTower/loftbox-sdk-go`	—
Rust	`cargo add loftbox-sdk`	—
PHP	`composer require loftbox/sdk`	Laravel
Java / Kotlin	`net.loftbox:loftbox-sdk`	Spring Boot
Ruby	`gem install loftbox`	Rails
C# / .NET	`dotnet add package LoftBox.Sdk`	ASP.NET Core (DI)

Sources and per-language quickstarts live in each GitHub repository under github.com/TheMagicTower (loftbox-sdk-<language>). Python, TypeScript, and Go are published to their registries; the remaining packages are rolling out to Packagist, Maven Central, RubyGems, NuGet, and crates.io — check the repo for current registry status.

प्रमाणीकरण

API प्रमाणीकरण

पर्सनल बीटा संगठन के लिए owner email रजिस्टर करके शुरुआत करें। owner को ईमेल द्वारा एक सत्यापन टोकन मिलता है; सत्यापन कॉल प्रारंभिक API key एक बार लौटाता है और owner स्वागत सूचना भेजता है।

export LOFTBOX_OWNER_EMAIL="[email protected]"

curl -i -X POST "$BASE_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "organization_name": "Example Agents",
    "slug": "example-agents"
  }'

export LOFTBOX_VERIFICATION_TOKEN="123456"

curl -i -X POST "$BASE_URL/v1/auth/signup/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "verification_token": "'"$LOFTBOX_VERIFICATION_TOKEN"'"
  }'

लौटाई गई server-side API key का उपयोग Authorization header के साथ करें। API keys को कभी भी ब्राउज़र, मोबाइल क्लाइंट, सार्वजनिक लॉग, या एनालिटिक्स इवेंट्स में उजागर न करें।

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

keys को server-side सीक्रेट स्टोरेज में संग्रहीत करें जैसे Fly secrets, deploy प्लेटफ़ॉर्म द्वारा प्रबंधित environment variables, या एक समर्पित सीक्रेट मैनेजर। असली keys को issue टिप्पणियों, स्क्रीनशॉट, एनालिटिक्स टूल, या ब्राउज़र कोड में पेस्ट न करें।

जब कोई ऑपरेटर छोड़े, कोई सीक्रेट लीक हो सकता हो, या किसी environment को अब API एक्सेस की आवश्यकता न हो, तो keys को rotate करें।

एजेंट सेटअप

वन-लाइन इंस्टॉल और एजेंट प्रॉम्प्ट

एजेंट सार्वजनिक LoftBox मेल स्किल्स इंस्टॉल कर सकते हैं, फिर केवल owner email के साथ ऑनबोर्डिंग फ़्लो चला सकते हैं। रजिस्ट्रेशन स्किल संगठन लेबल, स्थिर external_id, एजेंट slug, और मेलबॉक्स local part को वर्तमान एजेंट से प्राप्त करता है। रजिस्ट्रेशन के बाद, इंस्टॉल किए गए send और inbox-check स्किल्स जारी की गई API key और मेलबॉक्स ID का उपयोग करते हैं।

curl -fsSL https://loftbox.net/install.sh | sh

curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent codex
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent claude
curl -fsSL https://loftbox.net/install.sh | sh -s -- --target "$HOME/.my-agent/skills"

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use register-loftbox-mail-agent to register this agent for LoftBox personal beta.
Ask me only for my owner email.
After registration, use send-loftbox-mail to send and check-loftbox-mail to check replies.

curl -fsSL https://loftbox.net/install.sh | sh -s -- --check
curl -fsSL https://loftbox.net/install.sh | sh -s -- --update

अपडेट जाँच को केवल एक सूचना पथ के रूप में उपयोग करें। एक नया स्किल बंडल इंस्टॉल करना एजेंट व्यवहार बदलता है, इसलिए अपडेट ऑपरेटर अनुमोदन के बाद चलने चाहिए।

केवल तभी कोई अन्य मान माँगें जब एजेंट पहचान प्राप्त न की जा सके या कोई duplicate external ID किसी भिन्न एजेंट का हो।

डोमेन

Custom-domain ऑनबोर्डिंग

मेलबॉक्स द्वारा किसी डोमेन का उपयोग करने से पहले हर outbound डोमेन को सत्यापित किया जाना चाहिए। API स्वामित्व, inbound रूटिंग, sender alignment, और डिलीवरी सत्यापन के लिए आवश्यक DNS रिकॉर्ड लौटाता है।

डोमेन बनाएं POST /v1/domainsके साथ।
आवश्यक रिकॉर्ड प्राप्त करें GET /v1/domains/{id}/dnsके साथ।
अपने DNS host पर लौटाए गए TXT, MX, DKIM, और return-path रिकॉर्ड जोड़ें।
कॉल करें POST /v1/domains/{id}/verify DNS प्रसार के बाद।
प्रोडक्शन मेलबॉक्स बनाने से पहले प्रतीक्षा करें जब तक inbound और outbound दोनों स्थिति verified न हो जाएं।

curl -i "$BASE_URL/v1/domains" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

curl -i "$BASE_URL/v1/domains/domain_uuid/dns" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/domains/domain_uuid/verify" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

या किसी एजेंट को एकीकृत onboard-business-domain फ़्लो (email auth → domain onboard → DNS) के साथ संपूर्ण व्यावसायिक ऑनबोर्डिंग एंड टू एंड चलाने दें। इस प्रॉम्प्ट को अपने एजेंट में पेस्ट करें:

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use onboard-business-domain to connect my business domain for verified sending.
Ask me only for my owner email and the domain to send from.

1. Email auth: register my owner email. LoftBox emails a 6-digit token — ask me
   to paste it, then verify to obtain my organization API key (LoftBox-managed
   sending is available immediately once approved).
2. Domain onboard: run add <domain> (note the returned domain id), then read
   next_actions for the exact DNS records (TXT, DKIM, return-path, inbound MX).
   Show me each record (host, type, value).
3. DNS: let me add the records at my DNS host myself, or auto-apply them with
   apply-dns --provider route53|cloudflare using my own cloud credentials from
   the environment (they stay in my environment; LoftBox never receives them).
4. The domain re-verifies asynchronously on the server after DNS propagates.
   Poll status <domain_id> until inbound and outbound are both verified, then
   report — custom-domain sending activates once verified.
Operate only on my organization. Do not fabricate DNS values; use exactly what the API returns. If onboarding cannot proceed (domain previously deleted, or in use by another org), report it and stop.

आधिकारिक स्किल्स & स्रोत

onboard-business-domain और setup-loftbox-domain आधिकारिक LoftBox स्किल्स हैं। वे सार्वजनिक स्किल रिपॉज़िटरी में प्रकाशित हैं और इनके द्वारा इंस्टॉल किए जाते हैं https://loftbox.net/install.sh — यदि कोई एजेंट उन्हें नहीं ढूँढ पाता, तो उसका इंस्टॉल किया बंडल पुराना है और installer को फिर से चलाने से वे जुड़ जाते हैं।

रिपॉज़िटरी (सार्वजनिक): github.com/TheMagicTower/loftbox-agent-mail-skill
स्किल डायरेक्ट्रीज़: onboard-business-domain/, setup-loftbox-domain/
इंस्टॉल किया बंडल संस्करण & pinned commit: loftbox.net/skill-version.json

यह setup-loftbox-domain स्किल इसकी स्क्रिप्ट को सीधे चलाकर invoke की जाती है (installer एक setup-loftbox-domain shell कमांड नहीं बनाता)। $SKILL_DIR वहीं है जहाँ install.sh ने स्किल रखी — जैसे ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, या Hermes पर ~/.hermes/skills/email/setup-loftbox-domain। स्किल LoftBox API को कॉल करती है — ठीक उन्हीं DNS मानों का उपयोग करें जो API लौटाता है, उन्हें कभी न गढ़ें:

SKILL_DIR=<path to setup-loftbox-domain>   # e.g. ~/.claude/skills/setup-loftbox-domain

python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" add <domain>
   # onboard the domain (idempotent: resolves an existing active row on 409)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" dns <id>
   # list the exact DNS records to set (TXT, DKIM, return-path, MX)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" status <id>
   # structured status: inbound/outbound flags + next_actions
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" verify <id>
   # trigger verification after the DNS records are in place
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" apply-dns <id> --provider route53|cloudflare [--dry-run] [--overwrite]
   # auto-apply the next_actions records using cloud credentials from your OWN
   # environment (they never leave it). With no credentials, add the records
   # manually instead — onboarding still completes.

onboard-business-domain व्यवस्थित करता है register-loftbox-mail-agent (email auth) और setup-loftbox-domain (domain onboard + DNS) को एंड टू एंड। 6-अंकीय email टोकन चरण के लिए एक मनुष्य की आवश्यकता होती है, इसलिए यह पूरी तरह अनअटेंडेड नहीं है।

लॉन्च के लिए, पर्सनल बीटा LoftBox-managed डिलीवरी और LoftBox-managed inbound MX हैंडलिंग का उपयोग करता है। कस्टम डोमेन केवल सत्यापन के बाद सक्षम होते हैं।

मेलबॉक्स

एजेंट और मेलबॉक्स

एजेंट व्यावसायिक उद्देश्य, स्वामित्व संदर्भ, और स्थिर external ID रखते हैं। मेलबॉक्स उस एजेंट से एक पता और डोमेन जोड़ते हैं। डिस्प्ले नाम, owners, और policy scope को ऑपरेटर समीक्षा के लिए पर्याप्त स्पष्ट रखें।

प्रति ऑपरेशनल एजेंट या वर्कफ़्लो भूमिका एक मेलबॉक्स का उपयोग करें।
उपयोग करें external_id duplicate जाँच और idempotent एजेंट सेटअप के लिए।
प्रोडक्शन outbound मेल के लिए सत्यापित कस्टम डोमेन का उपयोग करें।
जब एजेंट उद्देश्य अस्पष्ट हो तो autonomous भेजना अक्षम करें या रोकें।

curl -i "$BASE_URL/v1/agents?external_id=hermes:support-agent" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "external_id": "hermes:support-agent",
    "description": "Handles controlled support follow-up",
    "purpose": "Reply to support conversations after policy checks",
    "owner_label": "Customer Operations",
    "policy_scope": "agent"
  }'

curl -i "$BASE_URL/v1/agents/agent_uuid/mailboxes" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "retention_days": 7
  }'

छोड़ दें domain_id LoftBox-managed पर्सनल बीटा डोमेन के लिए। यदि एजेंट के पास एक HTTPS endpoint हो तो एजेंट webhook को अलग से रजिस्टर करें।

सत्यापित कस्टम डोमेन पर आप एक मेलबॉक्स को catch-all के रूप में चिह्नित कर सकते हैं ("is_catch_all": true create या update पर)। उस डोमेन पर बिना सटीक मेलबॉक्स वाला कोई भी पता फिर उस पर route होता है — कैप्चर करने के लिए उपयोगी support@, sales@, या एकल एजेंट के साथ anything@yourdomain।

Outbound

संदेश भेजना

सत्यापित मेलबॉक्स से API के माध्यम से ऑपरेशनल या transactional संदेश भेजें। LoftBox डिलीवरी संदर्भ, डिलीवरी स्थिति, rate-limit निर्णय, और ऑपरेटर अनुमोदन परिणाम रिकॉर्ड करता है।

curl -i "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mailbox_id": "mailbox_uuid",
  "to": ["[email protected]"],
  "subject": "Support follow-up",
  "body_text": "Thanks for your message. We are checking this now.",
  "metadata": { "ticket_id": "ticket_123" },
  "send_at": "2030-01-01T09:00:00Z"
}'

पास करें send_at (RFC3339, भविष्य) डिलीवरी शेड्यूल करने के लिए, और एक Idempotency-Key header retries को dedupe करने के लिए (एक replay मूल संदेश लौटाता है)। भेजे या प्राप्त किए गए संदेशों को सूचीबद्ध करें और खोजें GET /v1/messages?q=<text>&label=<name>के साथ, और threads को व्यवस्थित करें POST/DELETE /v1/messages/{id}/labelsके माध्यम से।

LoftBox एक बल्क मार्केटिंग sender नहीं है। खरीदी गई सूचियाँ, scraped प्राप्तकर्ता, और सामान्य SMTP relay उपयोग MVP नीति के बाहर हैं।

Mail clients

IMAP / SMTP access

Besides the REST API and SDKs, you can connect any standard mail client or library over IMAP and SMTP. There is no separate mail password: authenticate with your LoftBox API key as the password and your full mailbox address as the username. Sending reuses the same pipeline as the API, so approval policy, rate limits, daily and storage caps, and audit logging all still apply.

Purpose	Host	Port	Security
Sending (SMTP, recommended)	`mail.loftbox.net`	`465`	SSL/TLS (implicit)
Sending (SMTP)	`mail.loftbox.net`	`587`	STARTTLS
Receiving (IMAP)	`mail.loftbox.net`	`993`	SSL/TLS (implicit)

Username is your mailbox address (for example bot-…@mail.loftbox.net), password is your API key — send scope for SMTP, receive scope for IMAP. IMAP exposes INBOX (incoming) and Sent (outgoing), read-only for now.

Mailboxes on the shared mail.loftbox.net domain support autoconfig: in Thunderbird and similar clients, entering the address and API key fills in the IMAP and SMTP settings automatically.

Inbound

Inbound webhooks और polling

उत्तर inbound संदेशों के रूप में संग्रहीत होते हैं। HTTPS endpoint वाले एजेंट signed webhook इवेंट्स प्राप्त कर सकते हैं; बिना endpoint वाले एजेंट को मेलबॉक्स inbox को poll करना चाहिए और प्रत्येक संसाधित संदेश को acknowledge करना चाहिए।

message.inboundएक नया inbound संदेश या उत्तर पार्स किया गया, थ्रेड किया गया, और कॉन्फ़िगर किए गए webhook के लिए उपलब्ध कराया गया।
message.deliveredप्राप्तकर्ता के लिए डिलीवरी रिपोर्ट की गई।
message.failedOutbound डिलीवरी स्थायी रूप से विफल हो गई या retry हैंडलिंग समाप्त हो गई।

curl -i "$BASE_URL/v1/agents/agent_uuid/webhooks" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/loftbox",
    "event_types": [
      "message.inbound",
      "message.delivered"
    ]
  }'

webhook सीक्रेट webhook बनाए जाने पर एक बार लौटाया जाता है। इसे तुरंत संग्रहीत करें और इवेंट सामग्री पर भरोसा करने से पहले हर inbound signature सत्यापित करें।

Every message.inbound event carries an injection_risk object — a prompt-injection heuristic score (0–1) plus the matched categories (instruction override, role hijack, tool injection, data exfiltration, hidden text, encoding evasion). The same value is on the message as injection_score. It is a signal only: LoftBox never blocks on it, so your agent decides how to act on untrusted inbound content — for example, requiring human approval above a threshold before following instructions found in an email.

To control which senders can reach an agent at all, manage per-mailbox or org-wide inbound allow/block lists via /v1/inbound-rules. Block a sender address or domain, or set an allowlist so only approved senders are accepted — anything else is refused at receive time (SMTP 550). Rules are evaluated against the SMTP envelope sender, not the spoofable From header.

curl -i "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox?limit=20" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox/ack" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["message_uuid_or_msg_public_id"]}'

Inbox acknowledgement and agent processing receipt are different signals. The inbox object does not embed receipt state: acknowledge removes a delivered inbound message from the polling queue, while an agent receipt tells operators whether the agent saw, processed, failed, or ignored that message.

curl -i -X POST "$BASE_URL/v1/messages/message_uuid_or_msg_public_id/agent-receipts" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "processed",
    "external_run_id": "agent-run-123",
    "summary": "Parsed and linked to the support ticket",
    "action_required": false
  }'

curl -i "$BASE_URL/v1/messages/message_uuid_or_msg_public_id/agent-status" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Recommended polling order: fetch inbox, process the message durably, post the agent receipt, then acknowledge the inbox item. If posting the receipt fails, retry it before acknowledging so the portal does not show a processed message with no receipt.

केवल तभी acknowledge करें जब एजेंट ने संदेश को टिकाऊ रूप से संसाधित कर लिया हो। खाली inbox polling को back off करना चाहिए; सक्रिय polling को 30-60 सेकंड जैसे मध्यम अंतराल का उपयोग करना चाहिए।

Inbound

रियलटाइम स्ट्रीमिंग (WebSocket)

वे एजेंट जो HTTPS webhook होस्ट नहीं कर सकते (उदाहरण के लिए, NAT या firewall के पीछे चल रहे हैं) एक WebSocket पर रियलटाइम में इवेंट्स की सदस्यता ले सकते हैं। स्ट्रीम webhooks के समान इवेंट प्रकार वहन करती है, sub-second डिलीवरी और डिस्कनेक्ट रहने के दौरान छूटे इवेंट्स के cursor-based replay के साथ। इसके लिए आवश्यक है receive scope।

GET /v1/wsWebSocket upgrade। प्रमाणित करें Authorization: Bearerके साथ। फ़िल्टर करें ?event_types= और ?agent_id=के साथ; फिर से शुरू करें ?after=<cursor>के साथ।
GET /v1/ws/asyncapi.jsonस्ट्रीम के लिए AsyncAPI विनिर्देश (सार्वजनिक)।

wscat -c "wss://api.loftbox.net/v1/ws?event_types=message.inbound" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

# frames: {"type":"ready",...} then {"type":"event","event":{...},"cursor":"..."}
# on reconnect, pass ?after=<last cursor> to replay missed events

एक error frame पर code के साथ lagged या resync_required, अंतिम प्राप्त cursor का उपयोग करके फिर से कनेक्ट करें।

एक्सेस नियंत्रण

अनुमतियाँ और API keys

API keys scopes वहन करती हैं। मोटे scopes (send, receive, admin) सूक्ष्म scopes को निहित करते हैं (message:send, message:read, domain:manage, approval:decide, keys:manage, …), इसलिए मौजूदा keys काम करती रहती हैं जबकि आप sub-agents के लिए least-privilege child keys जारी कर सकते हैं।

POST /v1/auth/keysएक child key जारी करें। अनुरोधित scopes कॉलर के scopes का एक subset होने चाहिए (कोई privilege escalation नहीं)। वैकल्पिक expires_in_days। Plaintext key एक बार लौटाई जाती है।
GET /v1/auth/keysorg keys सूचीबद्ध करें (केवल metadata, कोई secrets नहीं)। आवश्यक है keys:manage।
DELETE /v1/auth/keys/{id}एक key और उसके सभी descendants को निरस्त करें (cascade)। अनुमत है keys:manage या key के parent के लिए।

DMARC

DMARC aggregate रिपोर्ट

मेलबॉक्स प्रदाता (Gmail, Outlook, Yahoo, …) दैनिक DMARC aggregate (rua) रिपोर्ट भेजते हैं जो सारांशित करती हैं कि किन source IPs ने आपके सत्यापित डोमेन के रूप में मेल भेजा और क्या SPF/DKIM/DMARC aligned रहे। LoftBox इन्हें संरचित रिपोर्ट में ingest करता है ताकि आप deliverability की निगरानी कर सकें और spoofing पहचान सकें। प्रत्येक संग्रहीत रिपोर्ट प्रमाणित reporter डोमेन भी रिकॉर्ड करती है।

GET /v1/dmarc/reportsअपने संगठन की DMARC aggregate रिपोर्ट सूचीबद्ध करें, नवीनतम पहले। Cursor pagination के माध्यम से before_date_end + before_id (एक साथ लौटाए गए next_cursorके रूप में)। आवश्यक है domain:read।
GET /v1/dmarc/reports/{id}एक रिपोर्ट को उसके per-source-IP रिकॉर्ड (message count, disposition, DKIM/SPF alignment, header-from) के साथ प्राप्त करें। आवश्यक है domain:read।

curl -i "$BASE_URL/v1/dmarc/reports" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/dmarc/reports/REPORT_ID" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

रिपोर्ट तब प्रकट होती हैं जब प्रदाता उन्हें सबमिट करते हैं (आमतौर पर प्रति reporter प्रति दिन एक बार)। केवल आपके अपने सत्यापित डोमेन की रिपोर्ट लौटाई जाती हैं; प्लेटफ़ॉर्म या unhosted-domain रिपोर्ट कभी उजागर नहीं की जातीं।

इवेंट्स

डिलीवरी इवेंट्स

डिलीवरी स्थिति managed डिलीवरी callbacks और आंतरिक send स्थिति के बीच सामान्यीकृत की जाती है। समर्थन के लिए event IDs और डिलीवरी संदर्भ का उपयोग करें, निजी प्राप्तकर्ता डेटा का नहीं।

queued: LoftBox द्वारा डिलीवरी के लिए स्वीकृत।
sent: outbound डिलीवरी के लिए स्वीकृत।
delivered: प्राप्तकर्ता के लिए डिलीवरी रिपोर्ट की गई।
failed: डिलीवरी स्थायी रूप से विफल हुई या retries समाप्त हो गए।
blocked: नीति, rate limit, या रिपोर्ट नियंत्रण ने भेजना अवरुद्ध किया।

नियंत्रण

रेट लिमिट और रिपोर्ट नियंत्रण

Outbound भेजना संगठन, एजेंट, मेलबॉक्स, प्राप्तकर्ता, और डोमेन नीति द्वारा सीमित है। पर्सनल बीटा संगठन प्रति दिन 100 भेजने तक सीमित हैं। उच्च-जोखिम वाले संदेशों को डिलीवरी का प्रयास करने से पहले अनुमोदन के लिए रोका जा सकता है।

हैंडल करें 429 प्रतिक्रियाओं को back off करके। अनिश्चित काल तक retry न करें या किसी अन्य मेलबॉक्स से अनुमोदन holds को बायपास न करें।

HTTP/1.1 429 Too Many Requests
Retry-After: 60

डिलीवरी नियंत्रण

Managed डिलीवरी और सुरक्षा सेटअप

LoftBox बीटा खातों के लिए managed outbound डिलीवरी संचालित करता है। सार्वजनिक दस्तावेज़ीकरण को आंतरिक vendor नाम, क्रेडेंशियल, या रूटिंग विवरण उजागर किए बिना ग्राहक-दृश्य नियंत्रण का वर्णन करना चाहिए।

व्यवसाय की प्रकृति: सत्यापित-डोमेन AI एजेंटों के लिए API-managed ऑपरेशनल ईमेल पहचान।
ईमेल प्रकार: transactional/सिस्टम सूचनाएँ, सत्यापित उपयोगकर्ताओं द्वारा आरंभ किए गए एजेंट उत्तर, ऑनबोर्डिंग/टेस्ट संदेश, और रिपोर्ट/संपर्क हैंडलिंग।
नियंत्रण: केवल सत्यापित डोमेन, स्पष्ट rate limits, डिलीवरी लॉग, suppression/complaint हैंडलिंग, और निगरानी किया गया रिपोर्ट संपर्क।
सार्वजनिक पृष्ठ: गोपनीयता, शर्तें, और एंटी-स्पैम नीति।

DNS प्रसार और डिलीवरी सत्यापन holds को सेटअप स्थिति के रूप में माना जाना चाहिए, इस प्रमाण के रूप में नहीं कि API प्रॉक्सी या होमपेज डॉक्स टूटे हुए हैं।