Xây dựng quy trình email cho agent trên tên miền đã xác minh.

Bắt đầu

Bản beta cá nhân của LoftBox bắt đầu với một email chủ sở hữu. Đăng ký sẽ tạo tổ chức và gửi email một mã xác minh 6 chữ số. Chỉ sau khi xác minh email chủ sở hữu, LoftBox mới trả về khóa API đầu tiên, và khóa dạng văn bản thuần đó chỉ được hiển thị một lần. Việc xác minh cũng gửi cho chủ sở hữu một email chào mừng kèm các giới hạn beta và lộ trình đăng ký quản trị/thanh toán trong tương lai.

Tài khoản beta cá nhân được giới hạn 100 lượt gửi outbound mỗi ngày. Thời gian lưu giữ thư trong hộp thư mặc định là 7 ngày. Onboarding doanh nghiệp, thanh toán, thành viên tổ chức và các giới hạn lớn hơn là các mục trong lộ trình.

• POST /v1/auth/signupTạo một tổ chức beta cá nhân và gửi mã xác minh email chủ sở hữu.
• POST /v1/auth/signup/verifyXác minh email chủ sở hữu, nhận khóa API ban đầu một lần và kích hoạt thông báo chào mừng chủ sở hữu.
• POST /v1/agentsTạo một danh tính agent với chủ sở hữu, mục đích và phạm vi chính sách.
• POST /v1/domainsBắt đầu onboarding tên miền tùy chỉnh cho một tên miền bạn kiểm soát.
• POST /v1/agents/{agent_id}/mailboxesTạo một hộp thư beta do LoftBox quản lý hoặc một hộp thư trên tên miền tùy chỉnh đã xác minh.
• POST /v1/messagesGửi email vận hành từ hộp thư agent.
• GET /v1/mailboxes/{id}/inboxPoll các thư inbound chưa được xác nhận khi agent không có endpoint webhook.

Base URL và tài liệu đọc được bằng máy

Endpoint API công khai chính thức là https://api.loftbox.net. Trang chủ giữ một /api/* đường dẫn proxy để xác minh preview, nhưng các tích hợp production nên sử dụng hostname API chuyên dụng.

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

Kiểm tra edge và schema trước khi thiết lập tích hợp:

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

Route https://loftbox.net/api loại bỏ tiền tố /api và chuyển tiếp đến cùng một origin Fly API. Dùng nó cho việc kiểm tra preview trên Pages, không phải làm URL tích hợp chính.

Xác thực API

Bắt đầu bằng cách đăng ký email chủ sở hữu cho tổ chức beta cá nhân. Chủ sở hữu nhận được một mã xác minh qua email; lệnh gọi xác minh trả về khóa API ban đầu một lần và gửi thông báo chào mừng chủ sở hữu.

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

Sử dụng khóa API phía máy chủ được trả về với header Authorization . Không bao giờ để lộ khóa API trong trình duyệt, ứng dụng di động, log công khai hoặc sự kiện analytics.

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

Lưu trữ khóa trong kho bí mật phía máy chủ như Fly secrets, biến môi trường được quản lý bởi nền tảng deploy, hoặc một trình quản lý bí mật chuyên dụng. Không dán khóa thật vào bình luận issue, ảnh chụp màn hình, công cụ analytics hoặc mã trình duyệt.

Xoay khóa khi một người vận hành rời đi, một bí mật có thể đã bị rò rỉ, hoặc một môi trường không còn cần quyền truy cập API.

Cài đặt một dòng và prompt cho agent

Agent có thể cài đặt các kỹ năng mail LoftBox công khai, sau đó chạy luồng onboarding chỉ với email chủ sở hữu. Kỹ năng đăng ký suy ra nhãn tổ chức, một external_idổn định, slug agent, và phần local của hộp thư từ agent hiện tại. Sau khi đăng ký, các kỹ năng gửi và kiểm tra inbox đã cài đặt sử dụng khóa API và mailbox ID được cấp.

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

Chỉ dùng kiểm tra cập nhật như một kênh thông báo. Cài đặt một bộ kỹ năng mới sẽ thay đổi hành vi của agent, vì vậy việc cập nhật nên chạy sau khi người vận hành phê duyệt.

Chỉ yêu cầu một giá trị khác nếu danh tính agent không thể suy ra được hoặc một external ID trùng lặp thuộc về một agent khác.

Onboarding tên miền tùy chỉnh

Mọi tên miền outbound đều phải được xác minh trước khi hộp thư có thể sử dụng. API trả về các bản ghi DNS cần thiết cho quyền sở hữu, định tuyến inbound, căn chỉnh người gửi và xác minh gửi thư.

1. Tạo tên miền với POST /v1/domains.
2. Lấy các bản ghi bắt buộc với GET /v1/domains/{id}/dns.
3. Thêm các bản ghi TXT, MX, DKIM và return-path được trả về tại nhà cung cấp DNS của bạn.
4. Gọi POST /v1/domains/{id}/verify sau khi DNS lan truyền.
5. Chờ cho đến khi cả trạng thái inbound và outbound đều được xác minh trước khi tạo hộp thư production.

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"

Hoặc để một agent thực hiện toàn bộ quá trình onboarding doanh nghiệp từ đầu đến cuối với luồng hợp nhất onboard-business-domain (xác thực email → onboard tên miền → DNS). Dán prompt này vào agent của bạn:

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.

Kỹ năng & mã nguồn chính thức

onboard-business-domain và setup-loftbox-domain là các kỹ năng chính thức của LoftBox. Chúng được phát hành trong kho kỹ năng công khai và được cài đặt bởi https://loftbox.net/install.sh — nếu một agent không tìm thấy chúng, bộ kỹ năng đã cài của nó đã lỗi thời và chạy lại trình cài đặt sẽ thêm chúng vào.

• Kho lưu trữ (công khai): github.com/TheMagicTower/loftbox-agent-mail-skill
• Thư mục kỹ năng: onboard-business-domain/, setup-loftbox-domain/
• Phiên bản bộ kỹ năng đã cài & commit được ghim: loftbox.net/skill-version.json

Kỹ năng setup-loftbox-domain được gọi bằng cách chạy script của nó trực tiếp (trình cài đặt không tạo một setup-loftbox-domain lệnh shell). $SKILL_DIR là bất cứ nơi nào install.sh đặt kỹ năng — ví dụ ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, hoặc trên Hermes ~/.hermes/skills/email/setup-loftbox-domain. Kỹ năng gọi API LoftBox — sử dụng chính xác các giá trị DNS mà API trả về, không bao giờ bịa ra chúng:

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 điều phối register-loftbox-mail-agent (xác thực email) và setup-loftbox-domain (onboard tên miền + DNS) từ đầu đến cuối. Bước mã email 6 chữ số yêu cầu con người, nên nó không hoàn toàn tự động không giám sát.

Khi ra mắt, bản beta cá nhân sử dụng gửi thư do LoftBox quản lý và xử lý MX inbound do LoftBox quản lý. Tên miền tùy chỉnh chỉ được bật sau khi xác minh.

Agent và hộp thư

Agent giữ mục đích kinh doanh, bối cảnh sở hữu và external ID ổn định. Hộp thư gắn một địa chỉ và tên miền vào agent đó. Giữ tên hiển thị, chủ sở hữu và phạm vi chính sách đủ rõ ràng để người vận hành xem xét.

• Sử dụng một hộp thư cho mỗi agent vận hành hoặc vai trò quy trình.
• Sử dụng external_id để kiểm tra trùng lặp và thiết lập agent idempotent.
• Sử dụng tên miền tùy chỉnh đã xác minh cho thư outbound production.
• Vô hiệu hóa hoặc tạm giữ các lượt gửi tự động khi mục đích của agent không rõ ràng.

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

Bỏ qua domain_id cho tên miền beta cá nhân do LoftBox quản lý. Đăng ký webhook agent riêng nếu agent có một endpoint HTTPS.

Trên một tên miền tùy chỉnh đã xác minh, bạn có thể đánh dấu một hộp thư là catch-all ("is_catch_all": true khi tạo hoặc cập nhật). Bất kỳ địa chỉ nào tại tên miền đó mà không có hộp thư khớp chính xác sẽ được định tuyến đến nó — hữu ích để thu nhận support@, sales@, hoặc anything@yourdomain với một agent duy nhất.

Gửi thư

Gửi thư vận hành hoặc giao dịch qua API từ một hộp thư đã xác minh. LoftBox ghi lại tham chiếu gửi, trạng thái gửi, quyết định giới hạn tốc độ và kết quả phê duyệt của người vận hành.

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

Truyền send_at (RFC3339, tương lai) để lên lịch gửi, và một header Idempotency-Key để khử trùng lặp các lần thử lại (một lần phát lại trả về thư gốc). Liệt kê và tìm kiếm các thư đã gửi hoặc đã nhận với GET /v1/messages?q=<text>&label=<name>, và tổ chức các luồng thư qua POST/DELETE /v1/messages/{id}/labels.

LoftBox không phải là dịch vụ gửi marketing hàng loạt. Danh sách mua, người nhận thu thập bằng scrape, và việc sử dụng relay SMTP chung nằm ngoài chính sách MVP.

Webhook inbound và polling

Các phản hồi được lưu dưới dạng thư inbound. Các agent có endpoint HTTPS có thể nhận sự kiện webhook đã ký; các agent không có nên poll inbox của hộp thư và xác nhận mỗi thư đã xử lý.

• message.inboundMột thư inbound hoặc phản hồi mới đã được phân tích, sắp xếp theo luồng và cung cấp cho webhook được cấu hình.
• message.deliveredViệc gửi đã được báo cáo cho người nhận.
• message.failedViệc gửi outbound đã thất bại vĩnh viễn hoặc đã hết các lần xử lý thử lại.

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

Bí mật webhook được trả về một lần khi webhook được tạo. Lưu trữ nó ngay lập tức và xác minh mọi chữ ký inbound trước khi tin tưởng nội dung sự kiện.

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

Chỉ xác nhận sau khi agent đã xử lý thư một cách bền vững. Polling inbox trống nên giãn dần (back off); polling tích cực nên dùng khoảng thời gian vừa phải như 30-60 giây.

Streaming thời gian thực (WebSocket)

Các agent không thể host một webhook HTTPS (ví dụ, chạy sau NAT hoặc tường lửa) có thể đăng ký nhận sự kiện theo thời gian thực qua WebSocket. Luồng này mang cùng các loại sự kiện như webhook, với độ trễ dưới một giây và phát lại dựa trên cursor cho các sự kiện bị bỏ lỡ khi mất kết nối. Yêu cầu scope receive .

• GET /v1/wsNâng cấp WebSocket. Xác thực với Authorization: Bearer. Lọc với ?event_types= và ?agent_id=; tiếp tục với ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonĐặc tả AsyncAPI cho luồng (công khai).

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

Khi nhận một error frame với code lagged hoặc resync_required, kết nối lại bằng cursor nhận được cuối cùng.

Quyền và khóa API

Khóa API mang theo các scope. Các scope thô (send, receive, admin) ngụ ý các scope chi tiết (message:send, message:read, domain:manage, approval:decide, keys:manage, …), nên các khóa hiện có vẫn hoạt động trong khi bạn có thể cấp các khóa con với đặc quyền tối thiểu cho các sub-agent.

• POST /v1/auth/keysCấp một khóa con. Các scope được yêu cầu phải là tập con của scope của bên gọi (không leo thang đặc quyền). Tùy chọn expires_in_days. Khóa dạng văn bản thuần được trả về một lần.
• GET /v1/auth/keysLiệt kê các khóa của tổ chức (chỉ metadata, không có bí mật). Yêu cầu keys:manage.
• DELETE /v1/auth/keys/{id}Thu hồi một khóa và tất cả các khóa con của nó (cascade). Được phép cho keys:manage hoặc khóa cha của nó.

Báo cáo tổng hợp DMARC

Các nhà cung cấp hộp thư (Gmail, Outlook, Yahoo, …) gửi báo cáo tổng hợp DMARC (rua) hàng ngày tóm tắt những IP nguồn nào đã gửi thư dưới danh nghĩa các tên miền đã xác minh của bạn và liệu SPF/DKIM/DMARC có căn chỉnh hay không. LoftBox tiếp nhận chúng vào các báo cáo có cấu trúc để bạn có thể giám sát khả năng gửi thư và phát hiện giả mạo. Mỗi báo cáo được lưu trữ cũng ghi lại tên miền của bên báo cáo đã được xác thực.

• GET /v1/dmarc/reportsLiệt kê các báo cáo tổng hợp DMARC của tổ chức bạn, mới nhất trước. Phân trang theo cursor qua before_date_end + before_id (được trả về cùng nhau dưới dạng next_cursor). Yêu cầu domain:read.
• GET /v1/dmarc/reports/{id}Truy xuất một báo cáo cùng với các bản ghi theo từng IP nguồn của nó (số lượng thư, disposition, căn chỉnh DKIM/SPF, header-from). Yêu cầu 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"

Các báo cáo xuất hiện khi các nhà cung cấp gửi chúng (thường mỗi ngày một lần cho mỗi bên báo cáo). Chỉ các báo cáo cho các tên miền đã xác minh của riêng bạn được trả về; các báo cáo nền tảng hoặc tên miền không được host không bao giờ được hiển thị.

Sự kiện gửi

Trạng thái gửi được chuẩn hóa trên các callback gửi thư được quản lý và trạng thái gửi nội bộ. Sử dụng event ID và tham chiếu gửi để hỗ trợ, không phải dữ liệu riêng tư của người nhận.

• queued: được LoftBox chấp nhận để gửi.
• sent: được chấp nhận để gửi outbound.
• delivered: việc gửi đã được báo cáo cho người nhận.
• failed: việc gửi đã thất bại vĩnh viễn hoặc hết các lần thử lại.
• blocked: chính sách, giới hạn tốc độ, hoặc kiểm soát báo cáo đã chặn việc gửi.

Giới hạn tốc độ và kiểm soát báo cáo

Việc gửi outbound bị giới hạn bởi chính sách của tổ chức, agent, hộp thư, người nhận và tên miền. Các tổ chức beta cá nhân bị giới hạn ở 100 lượt gửi mỗi ngày. Các thư có rủi ro cao có thể bị tạm giữ để phê duyệt trước khi thử gửi.

Xử lý các phản hồi 429 bằng cách giãn dần (back off). Không thử lại vô thời hạn hoặc bỏ qua các lượt tạm giữ chờ phê duyệt từ một hộp thư khác.

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

Gửi thư được quản lý và thiết lập an toàn

LoftBox vận hành việc gửi outbound được quản lý cho các tài khoản beta. Tài liệu công khai nên mô tả các kiểm soát mà khách hàng nhìn thấy mà không để lộ tên nhà cung cấp nội bộ, thông tin xác thực hoặc chi tiết định tuyến.

• Bản chất kinh doanh: các danh tính email vận hành được quản lý bằng API cho các AI agent trên tên miền đã xác minh.
• Loại email: thông báo giao dịch/hệ thống, phản hồi của agent do người dùng đã xác minh khởi tạo, thư onboarding/kiểm thử, và xử lý báo cáo/liên hệ.
• Kiểm soát: chỉ tên miền đã xác minh, giới hạn tốc độ rõ ràng, log gửi thư, xử lý suppression/khiếu nại, và liên hệ báo cáo được giám sát.
• Trang công khai: Quyền riêng tư, Điều khoản, và Chính sách chống spam.

Việc lan truyền DNS và các lượt tạm giữ chờ xác minh gửi thư nên được coi là trạng thái thiết lập, chứ không phải bằng chứng cho thấy API proxy hoặc tài liệu trang chủ bị lỗi.