สร้างเวิร์กโฟลว์อีเมลเอเจนต์บนโดเมนที่ยืนยันแล้ว

การเริ่มต้นใช้งาน

LoftBox personal beta เริ่มต้นด้วยอีเมลของเจ้าของหนึ่งรายการ การสมัครจะสร้างองค์กรและส่งโทเคนการยืนยันแบบ 6 หลักทางอีเมล หลังจากยืนยันอีเมลของเจ้าของแล้วเท่านั้น LoftBox จึงจะคืน API key แรก และคีย์แบบ plaintext นั้นจะแสดงเพียงครั้งเดียว การยืนยันยังส่งอีเมลต้อนรับให้เจ้าของพร้อมลิมิตของ beta และเส้นทางการสมัคร admin/billing ในอนาคต

บัญชี personal beta จำกัดการส่งขาออกที่ 100 ครั้งต่อวัน การเก็บข้อความในกล่องเมลตั้งค่าเริ่มต้นไว้ที่ 7 วัน การออนบอร์ดสำหรับองค์กร การเรียกเก็บเงิน การเป็นสมาชิกองค์กร และลิมิตที่สูงขึ้นเป็นรายการในโรดแมป

• POST /v1/auth/signupสร้างองค์กร personal beta และส่งโทเคนการยืนยันอีเมลของเจ้าของ
• POST /v1/auth/signup/verifyยืนยันอีเมลของเจ้าของ รับ API key เริ่มต้นเพียงครั้งเดียว และทริกเกอร์ประกาศต้อนรับเจ้าของ
• POST /v1/agentsสร้างตัวตนของเอเจนต์พร้อมเจ้าของ วัตถุประสงค์ และขอบเขตนโยบาย
• POST /v1/domainsเริ่มการออนบอร์ดโดเมนแบบกำหนดเองสำหรับโดเมนที่คุณควบคุม
• POST /v1/agents/{agent_id}/mailboxesสร้างกล่องเมล beta ที่จัดการโดย LoftBox หรือกล่องเมลบนโดเมนแบบกำหนดเองที่ยืนยันแล้ว
• POST /v1/messagesส่งอีเมลเชิงปฏิบัติการจากกล่องเมลของเอเจนต์
• GET /v1/mailboxes/{id}/inboxดึงข้อความขาเข้าที่ยังไม่ได้รับทราบเมื่อเอเจนต์ไม่มี webhook endpoint
• 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 ทันที

รับคีย์ API ที่ใช้งานได้ด้วยการเรียกแบบไม่ต้องยืนยันตัวตนเพียงครั้งเดียวไปยัง POST /v1/auth/agent-signup ไม่ต้องสมัครผ่านคอนโซล เอเจนต์จึงเริ่มได้ทันที

จนกว่าเจ้าของจะยืนยัน (อ้างสิทธิ์) บัญชีทางอีเมล เอเจนต์จะสามารถส่งและรับได้กับที่อยู่เจ้าของเพียงที่อยู่เดียวเท่านั้น — เป็นวงจรปิด เจ้าของอ้างสิทธิ์ได้ที่ loftbox.net/claim (ลิงก์จะถูกส่งทางอีเมลโดยอัตโนมัติ) หรือผ่าน 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ยืนยันรหัสเพื่อเลื่อนบัญชีเป็นยืนยันแล้วและยกเลิกโหมดจำกัด

Base URL และเอกสารที่อ่านได้โดยเครื่อง

API endpoint สาธารณะตามมาตรฐานคือ https://api.loftbox.net. หน้าแรกจะคงไว้ซึ่ง /api/* พาธพร็อกซีสำหรับการยืนยันแบบ preview แต่การผสานรวมในโปรดักชันควรใช้ hostname ของ API ที่กำหนดไว้โดยเฉพาะ

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 จะตัด /api prefix ออกและส่งต่อไปยัง Fly API origin เดียวกัน ใช้สำหรับการตรวจสอบ Pages preview ไม่ใช่เป็น URL การผสานรวมหลัก

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.

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

เริ่มต้นด้วยการลงทะเบียนอีเมลของเจ้าของสำหรับองค์กร personal beta เจ้าของจะได้รับโทเคนการยืนยันทางอีเมล การเรียกการยืนยันจะคืน API key เริ่มต้นเพียงครั้งเดียวและส่งประกาศต้อนรับเจ้าของ

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"'"
  }'

ใช้ API key ฝั่งเซิร์ฟเวอร์ที่ได้รับคืนมากับ Authorization header อย่าเปิดเผย API keys ในเบราว์เซอร์ ไคลเอนต์มือถือ บันทึกสาธารณะ หรืออีเวนต์ analytics

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

จัดเก็บคีย์ไว้ในที่จัดเก็บความลับฝั่งเซิร์ฟเวอร์ เช่น Fly secrets ตัวแปรสภาพแวดล้อมที่จัดการโดยแพลตฟอร์มการ deploy หรือตัวจัดการความลับโดยเฉพาะ อย่าวางคีย์จริงลงในความคิดเห็น issue ภาพหน้าจอ เครื่องมือ analytics หรือโค้ดเบราว์เซอร์

หมุนคีย์เมื่อผู้ปฏิบัติงานออกจากตำแหน่ง เมื่อความลับอาจรั่วไหล หรือเมื่อสภาพแวดล้อมไม่ต้องการการเข้าถึง API อีกต่อไป

การติดตั้งแบบบรรทัดเดียวและพรอมต์เอเจนต์

เอเจนต์สามารถติดตั้งสกิลเมลสาธารณะของ LoftBox จากนั้นเรียกใช้โฟลว์การออนบอร์ดด้วยเพียงอีเมลของเจ้าของ สกิลการลงทะเบียนจะอนุมานป้ายชื่อองค์กร external_idที่เสถียร, slug ของเอเจนต์ และ local part ของกล่องเมลจากเอเจนต์ปัจจุบัน หลังการลงทะเบียน สกิลส่งและตรวจสอบกล่องเมลที่ติดตั้งจะใช้ API key และ mailbox 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

ใช้การตรวจสอบอัปเดตเป็นเส้นทางการแจ้งเตือนเท่านั้น การติดตั้งบันเดิลสกิลใหม่จะเปลี่ยนพฤติกรรมของเอเจนต์ ดังนั้นการอัปเดตควรดำเนินการหลังจากผู้ปฏิบัติงานอนุมัติ

ขอค่าอื่นเฉพาะเมื่อไม่สามารถอนุมานตัวตนของเอเจนต์ได้ หรือ external ID ที่ซ้ำกันเป็นของเอเจนต์อื่น

การออนบอร์ดโดเมนแบบกำหนดเอง

ทุกโดเมนขาออกต้องได้รับการยืนยันก่อนที่กล่องเมลจะใช้งานได้ API จะคืนเรคคอร์ด DNS ที่จำเป็นสำหรับการเป็นเจ้าของ การกำหนดเส้นทางขาเข้า การจัดแนวผู้ส่ง และการยืนยันการนำส่ง

1. สร้างโดเมนด้วย POST /v1/domains.
2. ดึงเรคคอร์ดที่จำเป็นด้วย GET /v1/domains/{id}/dns.
3. เพิ่มเรคคอร์ด TXT, MX, DKIM และ return-path ที่ได้รับคืนมาที่ DNS host ของคุณ
4. เรียก POST /v1/domains/{id}/verify หลังจาก DNS propagation
5. รอจนกว่าสถานะขาเข้าและขาออกจะได้รับการยืนยันทั้งคู่ก่อนสร้างกล่องเมลในโปรดักชัน

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 &rarr; domain onboard &rarr; 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.

สกิลทางการ &amp; ซอร์ส

onboard-business-domain และ setup-loftbox-domain เป็นสกิลทางการของ LoftBox เผยแพร่ใน repository สกิลสาธารณะและติดตั้งโดย https://loftbox.net/install.sh &mdash; หากเอเจนต์ไม่พบสกิลเหล่านั้น แสดงว่าบันเดิลที่ติดตั้งล้าสมัย และการเรียกใช้ตัวติดตั้งอีกครั้งจะเพิ่มสกิลเหล่านั้น

• Repository (สาธารณะ): github.com/TheMagicTower/loftbox-agent-mail-skill
• ไดเรกทอรีสกิล: onboard-business-domain/, setup-loftbox-domain/
• เวอร์ชันบันเดิลที่ติดตั้ง &amp; commit ที่ปักหมุด: loftbox.net/skill-version.json

สกิล setup-loftbox-domain ถูกเรียกใช้โดยการรันสคริปต์โดยตรง (ตัวติดตั้งไม่สร้างคำสั่งเชลล์ setup-loftbox-domain ) $SKILL_DIR คือที่ใดก็ตามที่ install.sh วางสกิลไว้ &mdash; เช่น ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, หรือบน Hermes ~/.hermes/skills/email/setup-loftbox-domain. สกิลจะเรียก LoftBox API &mdash; ใช้ค่า 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 หลักต้องใช้มนุษย์ จึงไม่เป็นแบบไม่มีคนดูแลทั้งหมด

สำหรับการเปิดตัว personal beta ใช้การนำส่งที่จัดการโดย LoftBox และการจัดการ MX ขาเข้าที่จัดการโดย LoftBox โดเมนแบบกำหนดเองจะเปิดใช้งานหลังจากการยืนยันเท่านั้น

เอเจนต์และกล่องเมล

เอเจนต์ถือวัตถุประสงค์ทางธุรกิจ บริบทความเป็นเจ้าของ และ external ID ที่เสถียร กล่องเมลจะแนบที่อยู่และโดเมนเข้ากับเอเจนต์นั้น รักษาชื่อที่แสดง เจ้าของ และขอบเขตนโยบายให้ชัดเจนพอสำหรับการตรวจสอบของผู้ปฏิบัติงาน

• ใช้หนึ่งกล่องเมลต่อหนึ่งเอเจนต์เชิงปฏิบัติการหรือบทบาทเวิร์กโฟลว์
• ใช้ external_id สำหรับการตรวจสอบความซ้ำซ้อนและการตั้งค่าเอเจนต์แบบ idempotent
• ใช้โดเมนแบบกำหนดเองที่ยืนยันแล้วสำหรับเมลขาออกในโปรดักชัน
• ปิดใช้งานหรือระงับการส่งอัตโนมัติเมื่อวัตถุประสงค์ของเอเจนต์ไม่ชัดเจน

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 สำหรับโดเมน personal beta ที่จัดการโดย LoftBox ลงทะเบียน webhook ของเอเจนต์แยกต่างหากหากเอเจนต์มี HTTPS endpoint

บนโดเมนแบบกำหนดเองที่ยืนยันแล้ว คุณสามารถทำเครื่องหมายกล่องเมลหนึ่งกล่องเป็น catch-all ("is_catch_all": true ตอนสร้างหรืออัปเดต) ที่อยู่ใดก็ตามในโดเมนนั้นที่ไม่มีกล่องเมลตรงกันพอดีจะถูกกำหนดเส้นทางไปยังกล่องนั้น — มีประโยชน์สำหรับการรับ support@, sales@, หรือ anything@yourdomain ด้วยเอเจนต์เดียว

การส่งข้อความ

ส่งข้อความเชิงปฏิบัติการหรือเชิงธุรกรรมผ่าน API จากกล่องเมลที่ยืนยันแล้ว LoftBox จะบันทึกการอ้างอิงการนำส่ง สถานะการนำส่ง การตัดสินใจเรื่องลิมิตอัตรา และผลการอนุมัติของผู้ปฏิบัติงาน

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 เพื่อขจัดความซ้ำซ้อนของการลองใหม่ (การรีเพลย์จะคืนข้อความต้นฉบับ) แสดงรายการและค้นหาข้อความที่ส่งหรือรับด้วย GET /v1/messages?q=<text>&label=<name>, และจัดระเบียบเธรดผ่าน POST/DELETE /v1/messages/{id}/labels.

LoftBox ไม่ใช่ตัวส่งการตลาดจำนวนมาก รายชื่อที่ซื้อมา ผู้รับที่ scrape มา และการใช้ SMTP relay ทั่วไปอยู่นอกนโยบาย MVP

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.

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.

Webhooks ขาเข้าและการ polling

การตอบกลับจะถูกจัดเก็บเป็นข้อความขาเข้า เอเจนต์ที่มี HTTPS endpoint สามารถรับอีเวนต์ webhook ที่ลงนามได้ ส่วนเอเจนต์ที่ไม่มีควร poll กล่องเมลขาเข้าและรับทราบข้อความที่ประมวลผลแล้วแต่ละรายการ

• message.inboundข้อความขาเข้าหรือการตอบกลับใหม่ถูก parse จัดเธรด และทำให้พร้อมใช้งานสำหรับ webhook ที่กำหนดค่าไว้
• message.deliveredมีการรายงานการนำส่งสำหรับผู้รับ
• message.failedการนำส่งขาออกล้มเหลวอย่างถาวรหรือใช้การจัดการการลองใหม่จนหมด

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 secret จะถูกคืนเพียงครั้งเดียวเมื่อสร้าง webhook จัดเก็บทันทีและยืนยันลายเซ็นขาเข้าทุกรายการก่อนเชื่อถือเนื้อหาอีเวนต์

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.

รับทราบหลังจากที่เอเจนต์ประมวลผลข้อความอย่างคงทนแล้วเท่านั้น การ poll กล่องเมลที่ว่างเปล่าควร back off ส่วนการ poll ที่ใช้งานควรใช้ช่วงเวลาปานกลาง เช่น 30-60 วินาที

การสตรีมแบบเรียลไทม์ (WebSocket)

เอเจนต์ที่ไม่สามารถโฮสต์ HTTPS webhook ได้ (เช่น ทำงานอยู่หลัง NAT หรือไฟร์วอลล์) สามารถสมัครรับอีเวนต์แบบเรียลไทม์ผ่าน WebSocket สตรีมจะส่งอีเวนต์ประเภทเดียวกับ webhooks ด้วยการนำส่งระดับต่ำกว่าวินาทีและการรีเพลย์อีเวนต์ที่พลาดไประหว่างตัดการเชื่อมต่อแบบอิงเคอร์เซอร์ ต้องใช้ scope receive scope

• GET /v1/wsการอัปเกรด WebSocket ยืนยันตัวตนด้วย 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 ที่มีโค้ด lagged หรือ resync_required, ให้เชื่อมต่อใหม่โดยใช้เคอร์เซอร์ล่าสุดที่ได้รับ

สิทธิ์และ API keys

API keys ถือ scope ต่างๆ scope แบบหยาบ (send, receive, admin) บ่งบอกถึง scope แบบละเอียด (message:send, message:read, domain:manage, approval:decide, keys:manage, …) ดังนั้นคีย์ที่มีอยู่จึงยังคงทำงานได้ในขณะที่คุณสามารถออกคีย์ลูกที่มีสิทธิ์น้อยที่สุดสำหรับเอเจนต์ย่อยได้

• POST /v1/auth/keysออกคีย์ลูก scope ที่ร้องขอต้องเป็น subset ของผู้เรียก (ไม่มีการยกระดับสิทธิ์) ทางเลือก expires_in_days. คีย์แบบ plaintext จะถูกคืนเพียงครั้งเดียว
• GET /v1/auth/keysแสดงรายการคีย์ขององค์กร (เฉพาะ metadata ไม่มีความลับ) ต้องใช้ keys:manage.
• DELETE /v1/auth/keys/{id}เพิกถอนคีย์และลูกหลานทั้งหมด (cascade) อนุญาตสำหรับ keys:manage หรือ parent ของคีย์

รายงานรวม DMARC

ผู้ให้บริการกล่องเมล (Gmail, Outlook, Yahoo, …) จะส่งรายงานรวม DMARC (rua) รายวันที่สรุปว่า IP ต้นทางใดส่งเมลในนามโดเมนที่ยืนยันแล้วของคุณ และ SPF/DKIM/DMARC จัดแนวกันหรือไม่ LoftBox จะนำเข้าข้อมูลเหล่านี้เป็นรายงานแบบมีโครงสร้างเพื่อให้คุณตรวจสอบความสามารถในการนำส่งและตรวจจับการปลอมแปลง รายงานที่จัดเก็บแต่ละรายการยังบันทึกโดเมนผู้รายงานที่ยืนยันตัวตนแล้วด้วย

• GET /v1/dmarc/reportsแสดงรายการรายงานรวม DMARC ขององค์กรคุณ เรียงจากใหม่ที่สุด การแบ่งหน้าแบบเคอร์เซอร์ผ่าน before_date_end + before_id (คืนพร้อมกันเป็น next_cursor). ต้องใช้ domain:read.
• GET /v1/dmarc/reports/{id}ดึงรายงานหนึ่งฉบับพร้อมเรคคอร์ดต่อ IP ต้นทาง (จำนวนข้อความ, disposition, การจัดแนว DKIM/SPF, 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"

รายงานจะปรากฏเมื่อผู้ให้บริการส่งมา (โดยทั่วไปวันละครั้งต่อผู้รายงาน) จะคืนเฉพาะรายงานสำหรับโดเมนที่ยืนยันแล้วของคุณเองเท่านั้น รายงานของแพลตฟอร์มหรือโดเมนที่ไม่ได้โฮสต์จะไม่ถูกเปิดเผยเลย

อีเวนต์การนำส่ง

สถานะการนำส่งจะถูกทำให้เป็นมาตรฐานเดียวกันทั่วทั้ง callback การนำส่งที่จัดการและสถานะการส่งภายใน ใช้ event IDs และการอ้างอิงการนำส่งสำหรับการสนับสนุน ไม่ใช่ข้อมูลส่วนตัวของผู้รับ

• queued: ได้รับการยอมรับโดย LoftBox เพื่อการนำส่ง
• sent: ได้รับการยอมรับสำหรับการนำส่งขาออก
• delivered: มีการรายงานการนำส่งสำหรับผู้รับ
• failed: การนำส่งล้มเหลวอย่างถาวรหรือใช้การลองใหม่จนหมด
• blocked: นโยบาย ลิมิตอัตรา หรือการควบคุมรายงานได้บล็อกการส่ง

ลิมิตอัตราและการควบคุมรายงาน

การส่งขาออกถูกจำกัดด้วยนโยบายขององค์กร เอเจนต์ กล่องเมล ผู้รับ และโดเมน องค์กร personal beta ถูกจำกัดที่ 100 ครั้งต่อวัน ข้อความที่มีความเสี่ยงสูงสามารถถูกระงับเพื่อรออนุมัติก่อนที่จะพยายามนำส่ง

จัดการ 429 การตอบกลับด้วยการ back off อย่าลองใหม่ไม่จำกัดหรือข้ามการระงับเพื่ออนุมัติจากกล่องเมลอื่น

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

การนำส่งที่จัดการและการตั้งค่าความปลอดภัย

LoftBox ดำเนินการนำส่งขาออกที่จัดการสำหรับบัญชี beta เอกสารสาธารณะควรอธิบายการควบคุมที่ลูกค้ามองเห็นได้โดยไม่เปิดเผยชื่อผู้จำหน่ายภายใน ข้อมูลรับรอง หรือรายละเอียดการกำหนดเส้นทาง

• ลักษณะธุรกิจ: ตัวตนอีเมลเชิงปฏิบัติการที่จัดการผ่าน API สำหรับเอเจนต์ AI บนโดเมนที่ยืนยันแล้ว
• ประเภทอีเมล: การแจ้งเตือนเชิงธุรกรรม/ระบบ การตอบกลับของเอเจนต์ที่เริ่มต้นโดยผู้ใช้ที่ยืนยันแล้ว ข้อความออนบอร์ด/ทดสอบ และการจัดการรายงาน/การติดต่อ
• การควบคุม: เฉพาะโดเมนที่ยืนยันแล้ว ลิมิตอัตราที่ชัดเจน บันทึกการนำส่ง การจัดการ suppression/การร้องเรียน และผู้ติดต่อรายงานที่ถูกตรวจสอบ
• หน้าสาธารณะ: ความเป็นส่วนตัว, ข้อกำหนด, และ นโยบายต่อต้านสแปม.

การ propagate DNS และการระงับเพื่อยืนยันการนำส่งควรถือเป็นสถานะการตั้งค่า ไม่ใช่หลักฐานว่า API proxy หรือเอกสารหน้าแรกเสียหาย