Bangun alur kerja email agen dengan domain terverifikasi.

Memulai

Beta personal LoftBox dimulai dengan satu email pemilik. Pendaftaran membuat organisasi dan mengirimkan token verifikasi 6 digit melalui email. Hanya setelah verifikasi email pemilik, LoftBox mengembalikan kunci API pertama, dan kunci plaintext tersebut ditampilkan sekali saja. Verifikasi juga mengirimkan email selamat datang kepada pemilik berisi batas beta dan jalur pendaftaran admin/penagihan di masa depan.

Akun beta personal dibatasi 100 pengiriman keluar per hari. Retensi pesan kotak surat secara default 7 hari. Onboarding enterprise, penagihan, keanggotaan organisasi, dan batas yang lebih besar adalah item roadmap.

• POST /v1/auth/signupBuat organisasi beta personal dan kirim token verifikasi email pemilik.
• POST /v1/auth/signup/verifyVerifikasi email pemilik, terima kunci API awal sekali saja, dan picu pemberitahuan selamat datang untuk pemilik.
• POST /v1/agentsBuat identitas agen dengan pemilik, tujuan, dan cakupan kebijakan.
• POST /v1/domainsMulai onboarding domain kustom untuk domain yang Anda kendalikan.
• POST /v1/agents/{agent_id}/mailboxesBuat kotak surat beta yang dikelola LoftBox atau kotak surat domain kustom yang terverifikasi.
• POST /v1/messagesKirim email operasional dari kotak surat agen.
• GET /v1/mailboxes/{id}/inboxPolling pesan masuk yang belum diakui ketika agen tidak memiliki endpoint webhook.

Base URL dan dokumentasi yang dapat dibaca mesin

Endpoint API publik kanonis adalah https://api.loftbox.net. Halaman beranda menyediakan jalur proxy /api/* untuk verifikasi pratinjau, tetapi integrasi produksi sebaiknya menggunakan hostname API khusus.

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

Periksa edge dan skema sebelum menyambungkan integrasi:

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

Rute https://loftbox.net/api menghapus prefiks /api dan meneruskan ke origin API Fly yang sama. Gunakan untuk pemeriksaan pratinjau Pages, bukan sebagai URL integrasi utama.

Autentikasi API

Mulai dengan mendaftarkan email pemilik untuk organisasi beta personal. Pemilik menerima token verifikasi melalui email; panggilan verifikasi mengembalikan kunci API awal sekali saja dan mengirimkan pemberitahuan selamat datang untuk pemilik.

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

Gunakan kunci API sisi server yang dikembalikan dengan header Authorization . Jangan pernah mengekspos kunci API di browser, klien seluler, log publik, atau peristiwa analitik.

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

Simpan kunci di penyimpanan rahasia sisi server seperti Fly secrets, variabel lingkungan yang dikelola oleh platform deploy, atau pengelola rahasia khusus. Jangan menempelkan kunci asli ke komentar issue, tangkapan layar, alat analitik, atau kode browser.

Rotasi kunci ketika seorang operator keluar, sebuah rahasia mungkin telah bocor, atau sebuah lingkungan tidak lagi memerlukan akses API.

Instalasi satu baris dan prompt agen

Agen dapat menginstal skill email LoftBox publik, lalu menjalankan alur onboarding hanya dengan email pemilik. Skill registrasi menurunkan label organisasi, external_idyang stabil, slug agen, dan local part kotak surat dari agen saat ini. Setelah registrasi, skill pengiriman dan pemeriksaan inbox yang terinstal menggunakan kunci API dan ID kotak surat yang diterbitkan.

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

Gunakan pemeriksaan pembaruan hanya sebagai jalur notifikasi. Menginstal bundel skill baru mengubah perilaku agen, jadi pembaruan sebaiknya dijalankan setelah persetujuan operator.

Hanya minta nilai lain jika identitas agen tidak dapat diturunkan atau external ID duplikat milik agen yang berbeda.

Onboarding domain kustom

Setiap domain keluar harus diverifikasi sebelum kotak surat dapat menggunakannya. API mengembalikan rekaman DNS yang diperlukan untuk kepemilikan, perutean masuk, penyelarasan pengirim, dan verifikasi pengiriman.

1. Buat domain dengan POST /v1/domains.
2. Ambil rekaman yang diperlukan dengan GET /v1/domains/{id}/dns.
3. Tambahkan rekaman TXT, MX, DKIM, dan return-path yang dikembalikan di host DNS Anda.
4. Panggil POST /v1/domains/{id}/verify setelah propagasi DNS.
5. Tunggu hingga status masuk dan keluar keduanya terverifikasi sebelum membuat kotak surat produksi.

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"

Atau biarkan agen menjalankan seluruh onboarding bisnis dari awal hingga akhir dengan alur onboard-business-domain terpadu (autentikasi email → onboarding domain → DNS). Tempelkan prompt ini ke agen Anda:

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.

Skill resmi & sumber

onboard-business-domain dan setup-loftbox-domain adalah skill resmi LoftBox. Keduanya dipublikasikan di repositori skill publik dan diinstal oleh https://loftbox.net/install.sh — jika agen tidak dapat menemukannya, bundel terinstalnya sudah usang dan menjalankan ulang installer akan menambahkannya.

• Repositori (publik): github.com/TheMagicTower/loftbox-agent-mail-skill
• Direktori skill: onboard-business-domain/, setup-loftbox-domain/
• Versi bundel terinstal & commit yang dipin: loftbox.net/skill-version.json

Skill setup-loftbox-domain dipanggil dengan menjalankan skripnya secara langsung (installer tidak membuat perintah shell setup-loftbox-domain ). $SKILL_DIR adalah di mana pun install.sh menempatkan skill — mis. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, atau di Hermes ~/.hermes/skills/email/setup-loftbox-domain. Skill memanggil API LoftBox — gunakan persis nilai DNS yang dikembalikan API, jangan pernah mengarangnya:

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 mengorkestrasi register-loftbox-mail-agent (autentikasi email) dan setup-loftbox-domain (onboarding domain + DNS) dari awal hingga akhir. Langkah token email 6 digit memerlukan manusia, jadi tidak sepenuhnya tanpa pengawasan.

Untuk peluncuran, beta personal menggunakan pengiriman yang dikelola LoftBox dan penanganan MX masuk yang dikelola LoftBox. Domain kustom diaktifkan hanya setelah verifikasi.

Agen dan kotak surat

Agen menyimpan tujuan bisnis, konteks kepemilikan, dan external ID yang stabil. Kotak surat melampirkan alamat dan domain ke agen tersebut. Jaga agar nama tampilan, pemilik, dan cakupan kebijakan cukup jelas untuk ditinjau operator.

• Gunakan satu kotak surat per agen operasional atau peran alur kerja.
• Gunakan external_id untuk pemeriksaan duplikat dan penyiapan agen yang idempoten.
• Gunakan domain kustom terverifikasi untuk email keluar produksi.
• Nonaktifkan atau tahan pengiriman otonom ketika tujuan agen tidak jelas.

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

Hilangkan domain_id untuk domain beta personal yang dikelola LoftBox. Daftarkan webhook agen secara terpisah jika agen memiliki endpoint HTTPS.

Pada domain kustom terverifikasi Anda dapat menandai satu kotak surat sebagai catch-all ("is_catch_all": true saat membuat atau memperbarui). Alamat apa pun di domain tersebut yang tidak memiliki kotak surat persis akan diarahkan ke sana — berguna untuk menangkap support@, sales@, atau anything@yourdomain dengan satu agen.

Mengirim pesan

Kirim pesan operasional atau transaksional melalui API dari kotak surat terverifikasi. LoftBox mencatat referensi pengiriman, status pengiriman, keputusan batas laju, dan hasil persetujuan operator.

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

Berikan send_at (RFC3339, masa depan) untuk menjadwalkan pengiriman, dan header Idempotency-Key untuk men-dedupe percobaan ulang (replay mengembalikan pesan asli). Daftar dan cari pesan terkirim atau diterima dengan GET /v1/messages?q=<text>&label=<name>, dan organisasikan thread melalui POST/DELETE /v1/messages/{id}/labels.

LoftBox bukan pengirim pemasaran massal. Daftar yang dibeli, penerima hasil scraping, dan penggunaan relay SMTP generik berada di luar kebijakan MVP.

Webhook masuk dan polling

Balasan disimpan sebagai pesan masuk. Agen dengan endpoint HTTPS dapat menerima peristiwa webhook yang ditandatangani; agen tanpa endpoint sebaiknya melakukan polling inbox kotak surat dan mengakui setiap pesan yang telah diproses.

• message.inboundPesan masuk atau balasan baru telah diurai, di-thread, dan tersedia untuk webhook yang dikonfigurasi.
• message.deliveredPengiriman dilaporkan untuk penerima.
• message.failedPengiriman keluar gagal secara permanen atau telah menghabiskan penanganan percobaan ulang.

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

Rahasia webhook dikembalikan sekali saja ketika webhook dibuat. Simpan segera dan verifikasi setiap tanda tangan masuk sebelum mempercayai konten peristiwa.

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

Hanya akui setelah agen secara tahan lama memproses pesan. Polling inbox kosong sebaiknya melakukan back off; polling aktif sebaiknya menggunakan interval moderat seperti 30-60 detik.

Streaming realtime (WebSocket)

Agen yang tidak dapat meng-host webhook HTTPS (misalnya, berjalan di belakang NAT atau firewall) dapat berlangganan peristiwa secara realtime melalui WebSocket. Stream membawa jenis peristiwa yang sama seperti webhook, dengan pengiriman sub-detik dan replay berbasis cursor untuk peristiwa yang terlewat saat terputus. Membutuhkan cakupan receive .

• GET /v1/wsUpgrade WebSocket. Autentikasi dengan Authorization: Bearer. Filter dengan ?event_types= dan ?agent_id=; lanjutkan dengan ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonSpesifikasi AsyncAPI untuk stream (publik).

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

Pada frame error dengan kode lagged atau resync_required, sambung ulang menggunakan cursor terakhir yang diterima.

Izin dan kunci API

Kunci API membawa cakupan. Cakupan kasar (send, receive, admin) menyiratkan cakupan rinci (message:send, message:read, domain:manage, approval:decide, keys:manage, …), sehingga kunci yang ada tetap berfungsi sementara Anda dapat menerbitkan kunci anak hak-istimewa-terkecil untuk sub-agen.

• POST /v1/auth/keysTerbitkan kunci anak. Cakupan yang diminta harus berupa subset dari cakupan pemanggil (tanpa eskalasi hak istimewa). Opsional expires_in_days. Kunci plaintext dikembalikan sekali saja.
• GET /v1/auth/keysDaftar kunci organisasi (hanya metadata, tanpa rahasia). Membutuhkan keys:manage.
• DELETE /v1/auth/keys/{id}Cabut sebuah kunci dan semua turunannya (cascade). Diizinkan untuk keys:manage atau induk kunci tersebut.

Laporan agregat DMARC

Penyedia kotak surat (Gmail, Outlook, Yahoo, …) mengirimkan laporan agregat DMARC (rua) harian yang merangkum IP sumber mana yang mengirim email sebagai domain terverifikasi Anda dan apakah SPF/DKIM/DMARC selaras. LoftBox mencerna laporan ini menjadi laporan terstruktur sehingga Anda dapat memantau deliverability dan mendeteksi spoofing. Setiap laporan yang disimpan juga mencatat domain pelapor yang terautentikasi.

• GET /v1/dmarc/reportsDaftar laporan agregat DMARC organisasi Anda, terbaru lebih dulu. Paginasi cursor melalui before_date_end + before_id (dikembalikan bersama sebagai next_cursor). Membutuhkan domain:read.
• GET /v1/dmarc/reports/{id}Ambil satu laporan dengan rekaman per-IP-sumbernya (jumlah pesan, disposisi, penyelarasan DKIM/SPF, header-from). Membutuhkan 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"

Laporan muncul saat penyedia mengirimkannya (biasanya sekali per hari per pelapor). Hanya laporan untuk domain terverifikasi Anda sendiri yang dikembalikan; laporan platform atau domain yang tidak di-host tidak pernah diekspos.

Peristiwa pengiriman

Status pengiriman dinormalisasi di seluruh callback pengiriman terkelola dan status pengiriman internal. Gunakan ID peristiwa dan referensi pengiriman untuk dukungan, bukan data penerima pribadi.

• queued: diterima oleh LoftBox untuk pengiriman.
• sent: diterima untuk pengiriman keluar.
• delivered: pengiriman dilaporkan untuk penerima.
• failed: pengiriman gagal secara permanen atau menghabiskan percobaan ulang.
• blocked: kebijakan, batas laju, atau kontrol laporan memblokir pengiriman.

Batas laju dan kontrol laporan

Pengiriman keluar dibatasi oleh kebijakan organisasi, agen, kotak surat, penerima, dan domain. Organisasi beta personal dibatasi 100 pengiriman per hari. Pesan berisiko tinggi dapat ditahan untuk persetujuan sebelum pengiriman dicoba.

Tangani respons 429 dengan melakukan back off. Jangan mencoba ulang tanpa henti atau melewati tahanan persetujuan dari kotak surat lain.

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

Pengiriman terkelola dan penyiapan keamanan

LoftBox mengoperasikan pengiriman keluar terkelola untuk akun beta. Dokumentasi publik sebaiknya menjelaskan kontrol yang terlihat pelanggan tanpa mengekspos nama vendor internal, kredensial, atau detail perutean.

• Sifat bisnis: identitas email operasional yang dikelola API untuk agen AI dengan domain terverifikasi.
• Jenis email: notifikasi transaksional/sistem, balasan agen yang diinisiasi oleh pengguna terverifikasi, pesan onboarding/uji, dan penanganan laporan/kontak.
• Kontrol: hanya domain terverifikasi, batas laju eksplisit, log pengiriman, penanganan suppression/keluhan, dan kontak laporan yang dipantau.
• Halaman publik: Privasi, Ketentuan, dan Kebijakan anti-spam.

Propagasi DNS dan tahanan verifikasi pengiriman sebaiknya diperlakukan sebagai status penyiapan, bukan sebagai bukti bahwa proxy API atau dokumentasi beranda rusak.