LoftBox Docs - API-Beta

Start

Erste Schritte

Die LoftBox-Personal-Beta beginnt mit einer einzigen Owner-E-Mail. Bei der Registrierung wird die Organisation erstellt und ein 6-stelliger Verifizierungstoken per E-Mail versendet. Erst nach der Verifizierung der Owner-E-Mail gibt LoftBox den ersten API-Schlüssel zurück, und dieser Klartext-Schlüssel wird nur einmal angezeigt. Die Verifizierung sendet dem Owner außerdem eine Willkommens-E-Mail mit den Beta-Limits und dem künftigen Registrierungspfad für Admin/Abrechnung.

Personal-Beta-Konten sind auf 100 ausgehende Sendungen pro Tag begrenzt. Die Aufbewahrung von Postfachnachrichten beträgt standardmäßig 7 Tage. Enterprise-Onboarding, Abrechnung, Organisationsmitgliedschaft und höhere Limits sind Roadmap-Elemente.

POST /v1/auth/signupErstellt eine Personal-Beta-Organisation und sendet den Verifizierungstoken für die Owner-E-Mail.
POST /v1/auth/signup/verifyVerifiziert die Owner-E-Mail, gibt einmalig den initialen API-Schlüssel zurück und löst die Willkommensbenachrichtigung für den Owner aus.
POST /v1/agentsErstellt eine Agent-Identität mit Owner, Zweck und Policy-Scope.
POST /v1/domainsStartet das Onboarding einer eigenen Domain, die Sie kontrollieren.
POST /v1/agents/{agent_id}/mailboxesErstellt ein LoftBox-verwaltetes Beta-Postfach oder ein Postfach mit verifizierter eigener Domain.
POST /v1/messagesSendet betriebliche E-Mails aus dem Agent-Postfach.
GET /v1/mailboxes/{id}/inboxRuft unbestätigte eingehende Nachrichten ab, wenn der Agent keinen Webhook-Endpoint hat.

Endpoint

Base-URL und maschinenlesbare Dokumentation

Der kanonische öffentliche API-Endpoint ist https://api.loftbox.net. Die Homepage behält einen /api/* Proxy-Pfad für die Preview-Verifizierung, aber Produktionsintegrationen sollten den dedizierten API-Hostnamen verwenden.

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

Prüfen Sie Edge und Schema, bevor Sie eine Integration anbinden:

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

Die https://loftbox.net/api Route entfernt das /api Präfix und leitet an denselben Fly-API-Origin weiter. Verwenden Sie sie für Pages-Preview-Prüfungen, nicht als primäre Integrations-URL.

Authentifizierung

API-Authentifizierung

Beginnen Sie mit der Registrierung der Owner-E-Mail für die Personal-Beta-Organisation. Der Owner erhält einen Verifizierungstoken per E-Mail; der Verifizierungsaufruf gibt einmalig den initialen API-Schlüssel zurück und sendet die Willkommensbenachrichtigung an den 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"'"
  }'

Verwenden Sie den zurückgegebenen serverseitigen API-Schlüssel mit dem Authorization Header. Geben Sie API-Schlüssel niemals in Browsern, mobilen Clients, öffentlichen Logs oder Analytics-Events preis.

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

Speichern Sie Schlüssel in serverseitigem Secret-Storage wie Fly-Secrets, von der Deploy-Plattform verwalteten Umgebungsvariablen oder einem dedizierten Secret-Manager. Fügen Sie keine echten Schlüssel in Issue-Kommentare, Screenshots, Analytics-Tools oder Browser-Code ein.

Rotieren Sie Schlüssel, wenn ein Operator ausscheidet, ein Secret möglicherweise geleakt wurde oder eine Umgebung keinen API-Zugriff mehr benötigt.

Agent-Einrichtung

Installation in einer Zeile und Agent-Prompt

Agenten können die öffentlichen LoftBox-Mail-Skills installieren und dann den Onboarding-Flow allein mit der Owner-E-Mail ausführen. Der Registrierungs-Skill leitet das Organisationslabel, die stabile external_id, den Agent-Slug und den Local-Part des Postfachs vom aktuellen Agenten ab. Nach der Registrierung verwenden die installierten Send- und Inbox-Check-Skills den ausgestellten API-Schlüssel und die Postfach-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

Verwenden Sie Update-Prüfungen ausschließlich als Benachrichtigungspfad. Die Installation eines neuen Skill-Bundles ändert das Verhalten des Agenten, daher sollten Updates erst nach Freigabe durch den Operator ausgeführt werden.

Fragen Sie nur dann nach einem weiteren Wert, wenn die Agent-Identität nicht abgeleitet werden kann oder eine doppelte externe ID zu einem anderen Agenten gehört.

Domains

Onboarding eigener Domains

Jede ausgehende Domain muss verifiziert werden, bevor Postfächer sie nutzen können. Die API gibt die DNS-Einträge zurück, die für Ownership, eingehendes Routing, Sender-Alignment und Zustellungsverifizierung erforderlich sind.

Erstellen Sie die Domain mit POST /v1/domains.
Rufen Sie die erforderlichen Einträge ab mit GET /v1/domains/{id}/dns.
Fügen Sie die zurückgegebenen TXT-, MX-, DKIM- und Return-Path-Einträge bei Ihrem DNS-Host hinzu.
Rufen Sie POST /v1/domains/{id}/verify nach der DNS-Propagierung auf.
Warten Sie, bis der eingehende und der ausgehende Status beide verifiziert sind, bevor Sie Produktionspostfächer erstellen.

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"

Oder lassen Sie einen Agenten das gesamte Business-Onboarding durchgängig steuern mit dem vereinheitlichten onboard-business-domain Flow (E-Mail-Authentifizierung → Domain-Onboarding → DNS). Fügen Sie diesen Prompt in Ihren Agenten ein:

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.

Offizielle Skills & Quelle

onboard-business-domain und setup-loftbox-domain sind offizielle LoftBox-Skills. Sie sind im öffentlichen Skill-Repository veröffentlicht und werden installiert von https://loftbox.net/install.sh — wenn ein Agent sie nicht finden kann, ist sein installiertes Bundle veraltet, und ein erneuter Lauf des Installers fügt sie hinzu.

Repository (öffentlich): github.com/TheMagicTower/loftbox-agent-mail-skill
Skill-Verzeichnisse: onboard-business-domain/, setup-loftbox-domain/
Installierte Bundle-Version & gepinnter Commit: loftbox.net/skill-version.json

Der setup-loftbox-domain Skill wird durch direkten Aufruf seines Skripts gestartet (der Installer erstellt keinen setup-loftbox-domain Shell-Befehl). $SKILL_DIR ist dort, wo install.sh den Skill abgelegt hat — z. B. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, oder auf Hermes ~/.hermes/skills/email/setup-loftbox-domain. Der Skill ruft die LoftBox-API auf — verwenden Sie genau die DNS-Werte, die die API zurückgibt, erfinden Sie sie niemals:

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 orchestriert register-loftbox-mail-agent (E-Mail-Authentifizierung) und setup-loftbox-domain (Domain-Onboarding + DNS) durchgängig. Der Schritt mit dem 6-stelligen E-Mail-Token erfordert einen Menschen, ist also nicht vollständig unbeaufsichtigt.

Zum Launch nutzt die Personal-Beta LoftBox-verwaltete Zustellung und LoftBox-verwaltetes eingehendes MX-Handling. Eigene Domains werden erst nach der Verifizierung aktiviert.

Postfächer

Agenten und Postfächer

Agenten halten den Business-Zweck, den Ownership-Kontext und die stabile externe ID. Postfächer verknüpfen eine Adresse und Domain mit diesem Agenten. Halten Sie Anzeigenamen, Owner und Policy-Scope klar genug für die Operator-Prüfung.

Verwenden Sie ein Postfach pro betrieblichem Agenten oder Workflow-Rolle.
Verwenden Sie external_id für Duplikatsprüfungen und idempotente Agent-Einrichtung.
Verwenden Sie verifizierte eigene Domains für ausgehende Produktionsmails.
Deaktivieren oder pausieren Sie autonome Sendungen, wenn der Zweck des Agenten unklar ist.

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

Lassen Sie domain_id für die LoftBox-verwaltete Personal-Beta-Domain weg. Registrieren Sie einen Agent-Webhook separat, wenn der Agent einen HTTPS-Endpoint hat.

Auf einer verifizierten eigenen Domain können Sie ein Postfach als Catch-all markieren ("is_catch_all": true beim Erstellen oder Aktualisieren). Jede Adresse dieser Domain ohne exaktes Postfach wird dann dorthin geroutet — nützlich, um support@, sales@, oder anything@yourdomain mit einem einzigen Agenten zu erfassen.

Ausgehend

Nachrichten senden

Senden Sie betriebliche oder transaktionale Nachrichten über die API aus einem verifizierten Postfach. LoftBox erfasst Zustellungsreferenzen, Zustellungsstatus, Rate-Limit-Entscheidungen und Ergebnisse der Operator-Freigabe.

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

Übergeben Sie send_at (RFC3339, in der Zukunft), um die Zustellung zu planen, und einen Idempotency-Key Header, um Retries zu deduplizieren (ein Replay gibt die ursprüngliche Nachricht zurück). Listen und durchsuchen Sie gesendete oder empfangene Nachrichten mit GET /v1/messages?q=<text>&label=<name>, und organisieren Sie Threads über POST/DELETE /v1/messages/{id}/labels.

LoftBox ist kein Massen-Marketing-Versender. Gekaufte Listen, gescrapte Empfänger und die Nutzung als generisches SMTP-Relay liegen außerhalb der MVP-Policy.

Eingehend

Eingehende Webhooks und Polling

Antworten werden als eingehende Nachrichten gespeichert. Agenten mit einem HTTPS-Endpoint können signierte Webhook-Events empfangen; Agenten ohne einen solchen sollten das Postfach-Inbox abfragen und jede verarbeitete Nachricht bestätigen.

message.inboundEine neue eingehende Nachricht oder Antwort wurde geparst, in einen Thread eingeordnet und dem konfigurierten Webhook bereitgestellt.
message.deliveredDie Zustellung wurde für den Empfänger gemeldet.
message.failedDie ausgehende Zustellung ist dauerhaft fehlgeschlagen oder das Retry-Handling ist erschöpft.

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

Das Webhook-Secret wird einmalig zurückgegeben, wenn der Webhook erstellt wird. Speichern Sie es sofort und verifizieren Sie jede eingehende Signatur, bevor Sie dem Event-Inhalt vertrauen.

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

Bestätigen Sie erst, nachdem der Agent die Nachricht dauerhaft verarbeitet hat. Bei leerem Inbox-Polling sollte ein Backoff erfolgen; aktives Polling sollte ein moderates Intervall wie 30-60 Sekunden verwenden.

Eingehend

Echtzeit-Streaming (WebSocket)

Agenten, die keinen HTTPS-Webhook hosten können (zum Beispiel hinter NAT oder einer Firewall), können Events in Echtzeit über einen WebSocket abonnieren. Der Stream transportiert dieselben Event-Typen wie Webhooks, mit Zustellung im Sub-Sekunden-Bereich und cursorbasiertem Replay von Events, die während der Trennung verpasst wurden. Erfordert den receive Scope.

GET /v1/wsWebSocket-Upgrade. Authentifizieren Sie sich mit Authorization: Bearer. Filtern Sie mit ?event_types= und ?agent_id=; setzen Sie fort mit ?after=<cursor>.
GET /v1/ws/asyncapi.jsonAsyncAPI-Spezifikation für den Stream (öffentlich).

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

Bei einem error Frame mit Code lagged oder resync_requiredverbinden Sie sich mit dem zuletzt empfangenen Cursor erneut.

Zugriffssteuerung

Berechtigungen und API-Schlüssel

API-Schlüssel tragen Scopes. Grobe Scopes (send, receive, admin) implizieren feingranulare Scopes (message:send, message:read, domain:manage, approval:decide, keys:manage, …), sodass bestehende Schlüssel weiterhin funktionieren, während Sie Child-Schlüssel mit minimalen Rechten für Sub-Agenten ausstellen können.

POST /v1/auth/keysStellt einen Child-Schlüssel aus. Angeforderte Scopes müssen eine Teilmenge der Scopes des Aufrufers sein (keine Rechteausweitung). Optional expires_in_days. Klartext-Schlüssel wird einmalig zurückgegeben.
GET /v1/auth/keysListet Org-Schlüssel auf (nur Metadaten, keine Secrets). Erfordert keys:manage.
DELETE /v1/auth/keys/{id}Widerruft einen Schlüssel und alle seine Nachkommen (Kaskade). Erlaubt für keys:manage oder das Parent des Schlüssels.

DMARC

DMARC-Aggregatberichte

Mailbox-Provider (Gmail, Outlook, Yahoo, …) senden täglich DMARC-Aggregatberichte (rua), die zusammenfassen, welche Quell-IPs E-Mails als Ihre verifizierten Domains versendet haben und ob SPF/DKIM/DMARC ausgerichtet waren. LoftBox erfasst diese in strukturierten Berichten, sodass Sie die Zustellbarkeit überwachen und Spoofing erkennen können. Jeder gespeicherte Bericht erfasst außerdem die authentifizierte Reporter-Domain.

GET /v1/dmarc/reportsListet die DMARC-Aggregatberichte Ihrer Organisation auf, neueste zuerst. Cursor-Pagination über before_date_end + before_id (zusammen zurückgegeben als next_cursor). Erfordert domain:read.
GET /v1/dmarc/reports/{id}Ruft einen Bericht mit seinen Einträgen pro Quell-IP ab (Nachrichtenanzahl, Disposition, DKIM/SPF-Alignment, Header-From). Erfordert 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"

Berichte erscheinen, sobald die Provider sie übermitteln (typischerweise einmal pro Tag und Reporter). Es werden nur Berichte für Ihre eigenen verifizierten Domains zurückgegeben; Berichte für Plattform- oder nicht gehostete Domains werden niemals offengelegt.

Ereignisse

Zustellungsereignisse

Der Zustellungsstatus wird über verwaltete Zustellungs-Callbacks und den internen Send-State hinweg normalisiert. Verwenden Sie Event-IDs und Zustellungsreferenzen für den Support, nicht private Empfängerdaten.

queued: von LoftBox zur Zustellung angenommen.
sent: zur ausgehenden Zustellung angenommen.
delivered: die Zustellung wurde für den Empfänger gemeldet.
failed: die Zustellung ist dauerhaft fehlgeschlagen oder die Retries sind erschöpft.
blocked: Policy, Rate-Limit oder Report-Control hat den Versand blockiert.

Steuerung

Rate-Limits und Report-Controls

Der ausgehende Versand wird durch Policys für Organisation, Agent, Postfach, Empfänger und Domain begrenzt. Personal-Beta-Organisationen sind auf 100 Sendungen pro Tag begrenzt. Nachrichten mit hohem Risiko können zur Freigabe zurückgehalten werden, bevor ein Zustellversuch erfolgt.

Behandeln Sie 429 Antworten mit einem Backoff. Wiederholen Sie nicht unbegrenzt und umgehen Sie keine Freigabe-Holds aus einem anderen Postfach.

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

Zustellungssteuerung

Verwaltete Zustellung und Sicherheits-Einrichtung

LoftBox betreibt eine verwaltete ausgehende Zustellung für Beta-Konten. Die öffentliche Dokumentation sollte die für Kunden sichtbaren Steuerungen beschreiben, ohne interne Vendor-Namen, Credentials oder Routing-Details offenzulegen.

Geschäftscharakter: API-verwaltete betriebliche E-Mail-Identitäten für KI-Agenten mit verifizierten Domains.
E-Mail-Typen: transaktionale/System-Benachrichtigungen, Agent-Antworten, die von verifizierten Nutzern initiiert wurden, Onboarding-/Test-Nachrichten sowie Report-/Kontakt-Handling.
Steuerungen: nur verifizierte Domains, explizite Rate-Limits, Zustellungslogs, Suppression-/Beschwerde-Handling und überwachter Report-Kontakt.
Öffentliche Seiten: Datenschutz, AGB, und Anti-Spam-Richtlinie.

DNS-Propagierung und Zustellungsverifizierungs-Holds sollten als Einrichtungszustand behandelt werden, nicht als Beweis dafür, dass der API-Proxy oder die Homepage-Dokumentation defekt ist.