API beta dokümanları

Doğrulanmış alan adlı ajan e-posta iş akışları oluşturun.

Bu beta dokümanları; sahip e-postası doğrulaması, API kimlik doğrulaması, ajan beceri kurulumu, özel alan adı onboarding'i, ajan posta kutuları, gönderim, gelen webhook'lar, teslimat olayları, hız limitleri ve teslimat kontrollerini kapsar.

Başlangıç

Başlarken

LoftBox kişisel beta, tek bir sahip e-postasıyla başlar. Kayıt, organizasyonu oluşturur ve 6 haneli bir doğrulama token'ı gönderir. LoftBox ilk API anahtarını yalnızca sahip e-postası doğrulandıktan sonra döndürür ve bu düz metin anahtar yalnızca bir kez gösterilir. Doğrulama ayrıca sahibe, beta limitlerini ve gelecekteki admin/faturalandırma kayıt yolunu içeren bir hoş geldiniz e-postası gönderir.

Kişisel beta hesapları günde 100 giden gönderimle sınırlıdır. Posta kutusu mesaj saklama süresi varsayılan olarak 7 gündür. Kurumsal onboarding, faturalandırma, organizasyon üyeliği ve daha yüksek limitler yol haritası maddeleridir.

  • POST /v1/auth/signupBir kişisel beta organizasyonu oluşturun ve sahip e-postası doğrulama token'ını gönderin.
  • POST /v1/auth/signup/verifySahip e-postasını doğrulayın, ilk API anahtarını bir kez alın ve sahip hoş geldiniz bildirimini tetikleyin.
  • POST /v1/agentsSahip, amaç ve politika kapsamına sahip bir ajan kimliği oluşturun.
  • POST /v1/domainsKontrol ettiğiniz bir alan adı için özel alan adı onboarding'ini başlatın.
  • POST /v1/agents/{agent_id}/mailboxesLoftBox tarafından yönetilen bir beta posta kutusu veya doğrulanmış özel alan adlı bir posta kutusu oluşturun.
  • POST /v1/messagesAjan posta kutusundan operasyonel e-posta gönderin.
  • GET /v1/mailboxes/{id}/inboxAjanın bir webhook uç noktası olmadığında, onaylanmamış gelen mesajları sorgulayın.
Uç nokta

Temel URL ve makine tarafından okunabilir dokümanlar

Kanonik genel API uç noktası şudur: https://api.loftbox.net. Ana sayfa, önizleme doğrulaması için bir /api/* proxy yolu tutar, ancak üretim entegrasyonları özel API ana bilgisayar adını kullanmalıdır.

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

Bir entegrasyonu bağlamadan önce edge'i ve şemayı kontrol edin:

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

Şu https://loftbox.net/api rota, /api önekini kaldırır ve aynı Fly API origin'ine iletir. Bunu birincil entegrasyon URL'si olarak değil, Pages önizleme kontrolleri için kullanın.

Kimlik doğrulama

API kimlik doğrulama

Kişisel beta organizasyonu için sahip e-postasını kaydederek başlayın. Sahip, e-posta yoluyla bir doğrulama token'ı alır; doğrulama çağrısı ilk API anahtarını bir kez döndürür ve sahip hoş geldiniz bildirimini gönderir.

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

Döndürülen sunucu tarafı API anahtarını Authorization başlığıyla kullanın. API anahtarlarını asla tarayıcılarda, mobil istemcilerde, genel günlüklerde veya analitik olaylarında ifşa etmeyin.

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

Anahtarları, Fly secrets, dağıtım platformu tarafından yönetilen ortam değişkenleri veya özel bir secret yöneticisi gibi sunucu tarafı secret depolama alanında saklayın. Gerçek anahtarları sorun yorumlarına, ekran görüntülerine, analitik araçlarına veya tarayıcı koduna yapıştırmayın.

Bir operatör ayrıldığında, bir secret sızmış olabileceğinde veya bir ortamın artık API erişimine ihtiyacı kalmadığında anahtarları döndürün.

Ajan kurulumu

Tek satırlık kurulum ve ajan istemi

Ajanlar genel LoftBox mail becerilerini kurabilir, ardından yalnızca sahip e-postasıyla onboarding akışını çalıştırabilir. Kayıt becerisi; organizasyon etiketini, kararlı external_iddeğerini, ajan slug'ını ve posta kutusu yerel kısmını mevcut ajandan türetir. Kayıttan sonra, kurulu gönderim ve gelen kutusu kontrol becerileri, verilen API anahtarını ve posta kutusu ID'sini kullanır.

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

Güncelleme kontrollerini yalnızca bir bildirim yolu olarak kullanın. Yeni bir beceri paketi kurmak ajan davranışını değiştirir, bu nedenle güncellemeler operatör onayından sonra çalıştırılmalıdır.

Yalnızca ajan kimliği türetilemiyorsa veya yinelenen bir harici ID farklı bir ajana aitse başka bir değer isteyin.

Alan adları

Özel alan adı onboarding'i

Her giden alan adı, posta kutuları onu kullanabilmeden önce doğrulanmalıdır. API; sahiplik, gelen yönlendirme, gönderen hizalaması ve teslimat doğrulaması için gereken DNS kayıtlarını döndürür.

  1. Alan adını şununla oluşturun: POST /v1/domains.
  2. Gerekli kayıtları şununla getirin: GET /v1/domains/{id}/dns.
  3. Döndürülen TXT, MX, DKIM ve return-path kayıtlarını DNS sağlayıcınıza ekleyin.
  4. Şunu çağırın: POST /v1/domains/{id}/verify DNS yayılımından sonra.
  5. Üretim posta kutuları oluşturmadan önce hem gelen hem giden durumunun doğrulanmış olmasını bekleyin.
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"

Veya bir ajanın tüm iş onboarding'ini uçtan uca yürütmesine izin verin; birleşik onboard-business-domain akışıyla (e-posta kimlik doğrulama → alan adı onboarding → DNS). Bu istemi ajanınıza yapıştırı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.

Resmi beceriler &amp; kaynak

onboard-business-domain ve setup-loftbox-domain resmi LoftBox becerileridir. Genel beceri deposunda yayınlanır ve şununla kurulur: https://loftbox.net/install.sh &mdash; bir ajan bunları bulamıyorsa, kurulu paketi güncel değildir ve kurulumu yeniden çalıştırmak bunları ekler.

Şu setup-loftbox-domain beceri, betiğini doğrudan çalıştırarak çağrılır (kurulum bir setup-loftbox-domain shell komutu oluşturmaz). $SKILL_DIR değeri, install.sh beceriyi nereye yerleştirdiyse orasıdır &mdash; örn. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, veya Hermes üzerinde ~/.hermes/skills/email/setup-loftbox-domain. Beceri LoftBox API'sini çağırır &mdash; tam olarak API'nin döndürdüğü DNS değerlerini kullanın, asla uydurmayın:

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 şunları yönetir: register-loftbox-mail-agent (e-posta kimlik doğrulama) ve setup-loftbox-domain (alan adı onboarding + DNS) uçtan uca. 6 haneli e-posta token adımı bir insan gerektirir, bu nedenle tam olarak gözetimsiz değildir.

Lansman için kişisel beta, LoftBox tarafından yönetilen teslimatı ve LoftBox tarafından yönetilen gelen MX işlemeyi kullanır. Özel alan adları yalnızca doğrulamadan sonra etkinleştirilir.

Posta kutuları

Ajanlar ve posta kutuları

Ajanlar iş amacını, sahiplik bağlamını ve kararlı harici ID'yi tutar. Posta kutuları, o ajana bir adres ve alan adı bağlar. Görünen adları, sahipleri ve politika kapsamını operatör incelemesi için yeterince açık tutun.

  • Her operasyonel ajan veya iş akışı rolü için bir posta kutusu kullanın.
  • Şunu kullanın: external_id yinelenen kontroller ve idempotent ajan kurulumu için.
  • Üretim giden postası için doğrulanmış özel alan adları kullanın.
  • Ajan amacı belirsizken otonom gönderimleri devre dışı bırakın veya beklemeye alın.
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
  }'

Şunu atlayın: domain_id LoftBox tarafından yönetilen kişisel beta alan adı için. Ajanın bir HTTPS uç noktası varsa, ayrı bir ajan webhook'u kaydedin.

Doğrulanmış bir özel alan adında bir posta kutusunu catch-all olarak işaretleyebilirsiniz ("is_catch_all": true oluşturma veya güncellemede). O alan adında tam eşleşen posta kutusu olmayan herhangi bir adres bu kutuya yönlenir — şunları yakalamak için kullanışlıdır: support@, sales@, veya anything@yourdomain tek bir ajanla.

Giden

Mesaj gönderme

API üzerinden doğrulanmış bir posta kutusundan operasyonel veya işlemsel mesajlar gönderin. LoftBox; teslimat referanslarını, teslimat durumunu, hız limiti kararlarını ve operatör onay sonuçlarını kaydeder.

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

Şunu geçirin: send_at (RFC3339, gelecek) teslimatı zamanlamak için ve bir Idempotency-Key başlığı yeniden denemeleri tekilleştirmek için (bir replay orijinal mesajı döndürür). Gönderilen veya alınan mesajları şununla listeleyin ve arayın: GET /v1/messages?q=<text>&label=<name>, ve thread'leri şununla düzenleyin: POST/DELETE /v1/messages/{id}/labels.

LoftBox toplu pazarlama gönderici değildir. Satın alınmış listeler, kazınmış alıcılar ve genel SMTP relay kullanımı MVP politikasının dışındadır.

Gelen

Gelen webhook'lar ve sorgulama

Yanıtlar gelen mesajlar olarak saklanır. Bir HTTPS uç noktası olan ajanlar imzalı webhook olaylarını alabilir; uç noktası olmayanlar posta kutusu gelen kutusunu sorgulamalı ve işlenen her mesajı onaylamalıdır.

  • message.inboundYeni bir gelen mesaj veya yanıt ayrıştırıldı, thread'lendi ve yapılandırılmış webhook'a sunuldu.
  • message.deliveredAlıcı için teslimat bildirildi.
  • message.failedGiden teslimat kalıcı olarak başarısız oldu veya yeniden deneme işlemini tüketti.
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 oluşturulduğunda bir kez döndürülür. Hemen saklayın ve olay içeriğine güvenmeden önce her gelen imzayı doğrulayı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"]}'

Yalnızca ajan mesajı kalıcı olarak işledikten sonra onaylayın. Boş gelen kutusu sorgulaması geri çekilmelidir; aktif sorgulama 30-60 saniye gibi ölçülü bir aralık kullanmalıdır.

Gelen

Gerçek zamanlı akış (WebSocket)

Bir HTTPS webhook'u barındıramayan ajanlar (örneğin NAT veya güvenlik duvarı arkasında çalışanlar) bir WebSocket üzerinden gerçek zamanlı olarak olaylara abone olabilir. Akış, webhook'larla aynı olay türlerini saniyenin altında teslimatla ve bağlantı kesikken kaçırılan olayların imleç tabanlı replay'iyle taşır. Şu kapsamı gerektirir: receive kapsamı.

  • GET /v1/wsWebSocket yükseltmesi. Şununla kimlik doğrulayın: Authorization: Bearer. Şununla filtreleyin: ?event_types= ve ?agent_id=; şununla devam edin: ?after=<cursor>.
  • GET /v1/ws/asyncapi.jsonAkış için AsyncAPI spesifikasyonu (genel).
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

Bir error frame'inde, şu kodla: lagged veya resync_required, son alınan imleci kullanarak yeniden bağlanın.

Erişim kontrolü

İzinler ve API anahtarları

API anahtarları kapsamlar taşır. Kaba kapsamlar (send, receive, admin) ince taneli kapsamları ima eder (message:send, message:read, domain:manage, approval:decide, keys:manage, …), böylece mevcut anahtarlar çalışmaya devam ederken alt ajanlar için en az ayrıcalıklı alt anahtarlar verebilirsiniz.

  • POST /v1/auth/keysBir alt anahtar verin. İstenen kapsamlar, çağıranın kapsamlarının bir alt kümesi olmalıdır (ayrıcalık yükseltme yok). İsteğe bağlı expires_in_days. Düz metin anahtar bir kez döndürülür.
  • GET /v1/auth/keysOrganizasyon anahtarlarını listeleyin (yalnızca meta veri, secret yok). Şunu gerektirir: keys:manage.
  • DELETE /v1/auth/keys/{id}Bir anahtarı ve tüm alt öğelerini iptal edin (cascade). Şunlar için izin verilir: keys:manage veya anahtarın üst öğesi.
DMARC

DMARC toplu raporları

Posta sağlayıcıları (Gmail, Outlook, Yahoo, …) hangi kaynak IP'lerin doğrulanmış alan adlarınız olarak posta gönderdiğini ve SPF/DKIM/DMARC'ın hizalanıp hizalanmadığını özetleyen günlük DMARC toplu (rua) raporları gönderir. LoftBox bunları yapılandırılmış raporlara işler, böylece teslim edilebilirliği izleyebilir ve spoofing'i tespit edebilirsiniz. Saklanan her rapor ayrıca kimliği doğrulanmış raporlayıcı alan adını da kaydeder.

  • GET /v1/dmarc/reportsOrganizasyonunuzun DMARC toplu raporlarını, en yenisi önce olacak şekilde listeleyin. Şunlar aracılığıyla imleç sayfalama: before_date_end + before_id (birlikte şöyle döndürülür: next_cursor). Şunu gerektirir: domain:read.
  • GET /v1/dmarc/reports/{id}Kaynak IP başına kayıtlarıyla (mesaj sayısı, disposition, DKIM/SPF hizalaması, header-from) tek bir raporu alın. Şunu gerektirir: 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"

Raporlar sağlayıcılar gönderdikçe görünür (genellikle raporlayıcı başına günde bir kez). Yalnızca kendi doğrulanmış alan adlarınız için raporlar döndürülür; platform veya barındırılmayan alan adı raporları asla ifşa edilmez.

Olaylar

Teslimat olayları

Teslimat durumu, yönetilen teslimat geri çağrıları ve dahili gönderim durumu genelinde normalleştirilir. Destek için özel alıcı verisi değil, olay ID'lerini ve teslimat referanslarını kullanın.

  • queued: teslimat için LoftBox tarafından kabul edildi.
  • sent: giden teslimat için kabul edildi.
  • delivered: alıcı için teslimat bildirildi.
  • failed: teslimat kalıcı olarak başarısız oldu veya yeniden denemeleri tüketti.
  • blocked: politika, hız limiti veya rapor kontrolü gönderimi engelledi.
Kontroller

Hız limitleri ve rapor kontrolleri

Giden gönderim; organizasyon, ajan, posta kutusu, alıcı ve alan adı politikasıyla sınırlandırılır. Kişisel beta organizasyonları günde 100 gönderimle sınırlıdır. Yüksek riskli mesajlar, teslimat denenmeden önce onay için beklemeye alınabilir.

Şunu ele alın: 429 yanıtlarını geri çekilerek. Süresiz olarak yeniden denemeyin veya başka bir posta kutusundan onay beklemelerini atlamayın.

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

Yönetilen teslimat ve güvenlik kurulumu

LoftBox, beta hesapları için yönetilen giden teslimat işletir. Genel dokümantasyon, dahili tedarikçi adlarını, kimlik bilgilerini veya yönlendirme ayrıntılarını ifşa etmeden müşteriye görünür kontrolleri açıklamalıdır.

  • İşin niteliği: doğrulanmış alan adlı yapay zeka ajanları için API tarafından yönetilen operasyonel e-posta kimlikleri.
  • E-posta türleri: işlemsel/sistem bildirimleri, doğrulanmış kullanıcılar tarafından başlatılan ajan yanıtları, onboarding/test mesajları ve rapor/iletişim işleme.
  • Kontroller: yalnızca doğrulanmış alan adları, açık hız limitleri, teslimat günlükleri, suppression/şikayet işleme ve izlenen rapor iletişimi.
  • Genel sayfalar: Gizlilik, Koşullar, ve Anti-spam politikası.

DNS yayılımı ve teslimat doğrulama beklemeleri, API proxy'sinin veya ana sayfa dokümanlarının bozuk olduğunun kanıtı olarak değil, kurulum durumu olarak ele alınmalıdır.