Bouw e-mailworkflows voor agents met geverifieerd domein.

Aan de slag

De persoonlijke bèta van LoftBox begint met één eigenaars-e-mail. Bij aanmelding wordt de organisatie aangemaakt en wordt een 6-cijferig verificatietoken gemaild. Pas na verificatie van de eigenaars-e-mail geeft LoftBox de eerste API-sleutel terug, en die sleutel in platte tekst wordt eenmalig getoond. Verificatie stuurt de eigenaar ook een welkomstmail met de bètalimieten en het toekomstige aanmeldpad voor beheer/facturatie.

Accounts in de persoonlijke bèta zijn beperkt tot 100 uitgaande verzendingen per dag. De standaardbewaartermijn voor mailboxberichten is 7 dagen. Enterprise-onboarding, facturatie, organisatielidmaatschap en hogere limieten staan op de roadmap.

• POST /v1/auth/signupMaak een persoonlijke bèta-organisatie aan en verstuur het verificatietoken voor de eigenaars-e-mail.
• POST /v1/auth/signup/verifyVerifieer de eigenaars-e-mail, ontvang eenmalig de initiële API-sleutel en activeer de welkomstmelding voor de eigenaar.
• POST /v1/agentsMaak een agentidentiteit aan met eigenaar, doel en beleidsscope.
• POST /v1/domainsStart de onboarding van een eigen domein voor een domein dat je beheert.
• POST /v1/agents/{agent_id}/mailboxesMaak een door LoftBox beheerde bèta-mailbox of een geverifieerde mailbox op een eigen domein aan.
• POST /v1/messagesVerstuur operationele e-mail vanuit de agent-mailbox.
• GET /v1/mailboxes/{id}/inboxPoll niet-bevestigde inkomende berichten wanneer de agent geen webhook-endpoint heeft.

Basis-URL en machineleesbare documentatie

Het canonieke openbare API-endpoint is https://api.loftbox.net. De homepage houdt een /api/* proxy-pad aan voor previewverificatie, maar productie-integraties moeten de speciale API-hostnaam gebruiken.

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

Controleer de edge en het schema voordat je een integratie aansluit:

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

De https://loftbox.net/api route verwijdert de /api prefix en stuurt door naar dezelfde Fly API-origin. Gebruik deze voor Pages-previewcontroles, niet als de primaire integratie-URL.

API-authenticatie

Begin met het registreren van de eigenaars-e-mail voor de persoonlijke bèta-organisatie. De eigenaar ontvangt een verificatietoken per e-mail; de verificatie-aanroep geeft eenmalig de initiële API-sleutel terug en stuurt de welkomstmelding voor de eigenaar.

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

Gebruik de teruggegeven server-side API-sleutel met de Authorization header. Stel API-sleutels nooit bloot in browsers, mobiele clients, openbare logs of analytics-gebeurtenissen.

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

Sla sleutels op in server-side geheime opslag zoals Fly secrets, omgevingsvariabelen beheerd door het deployplatform of een speciale secret manager. Plak echte sleutels niet in issuereacties, schermafbeeldingen, analyticstools of browsercode.

Roteer sleutels wanneer een operator vertrekt, een geheim mogelijk is gelekt of een omgeving geen API-toegang meer nodig heeft.

Installatie met één regel en agentprompt

Agents kunnen de openbare LoftBox-mailvaardigheden installeren en vervolgens de onboardingflow uitvoeren met alleen de eigenaars-e-mail. De registratievaardigheid leidt het organisatielabel, de stabiele external_id, agent-slug en het lokale deel van de mailbox af van de huidige agent. Na registratie gebruiken de geïnstalleerde verzend- en inbox-controlevaardigheden de uitgegeven API-sleutel en 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

Gebruik updatecontroles uitsluitend als meldingspad. Het installeren van een nieuwe vaardighedenbundel verandert het gedrag van de agent, dus updates moeten na goedkeuring van de operator worden uitgevoerd.

Vraag alleen om een andere waarde als de agentidentiteit niet kan worden afgeleid of als een dubbele externe ID bij een andere agent hoort.

Onboarding van eigen domeinen

Elk uitgaand domein moet worden geverifieerd voordat mailboxen het kunnen gebruiken. De API geeft de DNS-records terug die nodig zijn voor eigendom, inkomende routering, afzenderuitlijning en afleveringsverificatie.

1. Maak het domein aan met POST /v1/domains.
2. Haal de vereiste records op met GET /v1/domains/{id}/dns.
3. Voeg de teruggegeven TXT-, MX-, DKIM- en return-path-records toe bij je DNS-host.
4. Roep POST /v1/domains/{id}/verify aan na DNS-propagatie.
5. Wacht tot zowel de inkomende als de uitgaande status geverifieerd zijn voordat je productie-mailboxen aanmaakt.

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"

Of laat een agent de hele zakelijke onboarding van begin tot eind uitvoeren met de geïntegreerde onboard-business-domain flow (e-mailauthenticatie → domein-onboarding → DNS). Plak deze prompt in je agent:

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.

Officiële vaardigheden & bron

onboard-business-domain en setup-loftbox-domain zijn officiële LoftBox-vaardigheden. Ze worden gepubliceerd in de openbare vaardighedenrepository en geïnstalleerd door https://loftbox.net/install.sh — als een agent ze niet kan vinden, is de geïnstalleerde bundel verouderd en voegt het opnieuw uitvoeren van het installatieprogramma ze toe.

• Repository (openbaar): github.com/TheMagicTower/loftbox-agent-mail-skill
• Vaardighedenmappen: onboard-business-domain/, setup-loftbox-domain/
• Versie geïnstalleerde bundel & vastgezette commit: loftbox.net/skill-version.json

De setup-loftbox-domain vaardigheid wordt aangeroepen door het script ervan rechtstreeks uit te voeren (het installatieprogramma maakt geen setup-loftbox-domain shell-commando aan). $SKILL_DIR is waar install.sh de vaardigheid heeft geplaatst — bijv. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, of op Hermes ~/.hermes/skills/email/setup-loftbox-domain. De vaardigheid roept de LoftBox-API aan — gebruik exact de DNS-waarden die de API teruggeeft, verzin ze nooit:

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 orkestreert register-loftbox-mail-agent (e-mailauthenticatie) en setup-loftbox-domain (domein-onboarding + DNS) van begin tot eind. De stap met het 6-cijferige e-mailtoken vereist een mens, dus het is niet volledig onbemand.

Voor de lancering gebruikt de persoonlijke bèta door LoftBox beheerde aflevering en door LoftBox beheerde inkomende MX-afhandeling. Eigen domeinen worden pas ingeschakeld na verificatie.

Agents en mailboxen

Agents bevatten het zakelijke doel, de eigendomscontext en de stabiele externe ID. Mailboxen koppelen een adres en domein aan die agent. Houd weergavenamen, eigenaren en beleidsscope duidelijk genoeg voor beoordeling door de operator.

• Gebruik één mailbox per operationele agent of workflowrol.
• Gebruik external_id voor duplicaatcontroles en idempotente agentconfiguratie.
• Gebruik geverifieerde eigen domeinen voor uitgaande productiemail.
• Schakel autonome verzendingen uit of houd ze vast wanneer het doel van de agent onduidelijk is.

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

Laat domain_id weg voor het door LoftBox beheerde persoonlijke bètadomein. Registreer een agent-webhook apart als de agent een HTTPS-endpoint heeft.

Op een geverifieerd eigen domein kun je één mailbox als catch-all markeren ("is_catch_all": true bij aanmaken of bijwerken). Elk adres op dat domein zonder exacte mailbox wordt dan ernaartoe gerouteerd — handig voor het opvangen van support@, sales@, of anything@jouwdomein met één agent.

Berichten verzenden

Verstuur operationele of transactionele berichten via de API vanuit een geverifieerde mailbox. LoftBox legt afleveringsreferenties, afleveringsstatus, snelheidslimietbeslissingen en goedkeuringsuitkomsten van de operator vast.

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

Geef send_at (RFC3339, in de toekomst) door om aflevering te plannen, en een Idempotency-Key header om herhaalpogingen te dedupliceren (een replay geeft het oorspronkelijke bericht terug). Lijst en doorzoek verzonden of ontvangen berichten met GET /v1/messages?q=<text>&label=<name>, en organiseer threads via POST/DELETE /v1/messages/{id}/labels.

LoftBox is geen bulkmarketingverzender. Gekochte lijsten, gescrapete ontvangers en algemeen gebruik van SMTP-relay vallen buiten het MVP-beleid.

Inkomende webhooks en polling

Antwoorden worden opgeslagen als inkomende berichten. Agents met een HTTPS-endpoint kunnen ondertekende webhook-gebeurtenissen ontvangen; agents zonder endpoint moeten de mailbox-inbox pollen en elk verwerkt bericht bevestigen.

• message.inboundEen nieuw inkomend bericht of antwoord is geparseerd, in een thread geplaatst en beschikbaar gemaakt voor de geconfigureerde webhook.
• message.deliveredAflevering aan de ontvanger is gerapporteerd.
• message.failedUitgaande aflevering is permanent mislukt of heeft de afhandeling van herhaalpogingen uitgeput.

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

Het webhook-geheim wordt eenmalig teruggegeven wanneer de webhook wordt aangemaakt. Sla het direct op en verifieer elke inkomende handtekening voordat je de inhoud van de gebeurtenis vertrouwt.

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

Bevestig pas nadat de agent het bericht duurzaam heeft verwerkt. Polling van een lege inbox moet terugschakelen; actieve polling moet een gematigd interval gebruiken, zoals 30-60 seconden.

Realtime streaming (WebSocket)

Agents die geen HTTPS-webhook kunnen hosten (bijvoorbeeld achter NAT of een firewall) kunnen zich realtime abonneren op gebeurtenissen via een WebSocket. De stream draagt dezelfde gebeurtenistypen als webhooks, met aflevering binnen een seconde en op cursor gebaseerde replay van gebeurtenissen die zijn gemist tijdens verbroken verbinding. Vereist de receive scope.

• GET /v1/wsWebSocket-upgrade. Authenticeer met Authorization: Bearer. Filter met ?event_types= en ?agent_id=; hervat met ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonAsyncAPI-specificatie voor de stream (openbaar).

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

Bij een error frame met code lagged of resync_required, maak opnieuw verbinding met de laatst ontvangen cursor.

Machtigingen en API-sleutels

API-sleutels dragen scopes. Grove scopes (send, receive, admin) impliceren fijnmazige scopes (message:send, message:read, domain:manage, approval:decide, keys:manage, …), zodat bestaande sleutels blijven werken terwijl je child-sleutels met minimale rechten kunt uitgeven voor sub-agents.

• POST /v1/auth/keysGeef een child-sleutel uit. Gevraagde scopes moeten een subset zijn van die van de aanroeper (geen rechtenescalatie). Optioneel expires_in_days. Sleutel in platte tekst wordt eenmalig teruggegeven.
• GET /v1/auth/keysLijst de organisatiesleutels (alleen metadata, geen geheimen). Vereist keys:manage.
• DELETE /v1/auth/keys/{id}Trek een sleutel en al zijn afstammelingen in (cascade). Toegestaan voor keys:manage of de ouder van de sleutel.

DMARC-aggregaatrapporten

Mailboxproviders (Gmail, Outlook, Yahoo, …) sturen dagelijkse DMARC-aggregaatrapporten (rua) die samenvatten welke bron-IP's mail hebben verstuurd als jouw geverifieerde domeinen en of SPF/DKIM/DMARC uitgelijnd waren. LoftBox verwerkt deze tot gestructureerde rapporten zodat je de afleverbaarheid kunt monitoren en spoofing kunt opsporen. Elk opgeslagen rapport registreert ook het geauthenticeerde domein van de rapporteur.

• GET /v1/dmarc/reportsLijst de DMARC-aggregaatrapporten van je organisatie, nieuwste eerst. Cursorpaginering via before_date_end + before_id (samen teruggegeven als next_cursor). Vereist domain:read.
• GET /v1/dmarc/reports/{id}Haal één rapport op met zijn records per bron-IP (berichtaantal, dispositie, DKIM/SPF-uitlijning, header-from). Vereist 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"

Rapporten verschijnen naarmate providers ze indienen (doorgaans eenmaal per dag per rapporteur). Alleen rapporten voor je eigen geverifieerde domeinen worden teruggegeven; rapporten van het platform of niet-gehoste domeinen worden nooit getoond.

Afleveringsgebeurtenissen

De afleveringsstatus is genormaliseerd over beheerde afleverings-callbacks en de interne verzendstatus. Gebruik gebeurtenis-ID's en afleveringsreferenties voor support, niet privégegevens van de ontvanger.

• queued: geaccepteerd door LoftBox voor aflevering.
• sent: geaccepteerd voor uitgaande aflevering.
• delivered: aflevering aan de ontvanger is gerapporteerd.
• failed: aflevering is permanent mislukt of heeft de herhaalpogingen uitgeput.
• blocked: beleid, snelheidslimiet of rapportcontrole heeft het verzenden geblokkeerd.

Snelheidslimieten en rapportcontroles

Uitgaand verzenden wordt beperkt door beleid van organisatie, agent, mailbox, ontvanger en domein. Organisaties in de persoonlijke bèta zijn gemaximeerd op 100 verzendingen per dag. Berichten met hoog risico kunnen voor goedkeuring worden vastgehouden voordat aflevering wordt geprobeerd.

Handel 429 antwoorden af door terug te schakelen. Probeer niet eindeloos opnieuw en omzeil geen goedkeuringsvasthoudingen vanuit een andere mailbox.

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

Beheerde aflevering en veiligheidsconfiguratie

LoftBox verzorgt beheerde uitgaande aflevering voor bèta-accounts. Openbare documentatie moet de voor de klant zichtbare controles beschrijven zonder interne leveranciersnamen, inloggegevens of routeringsdetails bloot te geven.

• Aard van de activiteit: via API beheerde operationele e-mailidentiteiten voor AI-agents met geverifieerd domein.
• E-mailtypen: transactionele/systeemmeldingen, agentantwoorden geïnitieerd door geverifieerde gebruikers, onboarding-/testberichten en afhandeling van rapporten/contact.
• Controles: alleen geverifieerde domeinen, expliciete snelheidslimieten, afleveringslogs, afhandeling van onderdrukking/klachten en gemonitord rapportcontact.
• Openbare pagina's: Privacy, Voorwaarden, en Antispambeleid.

DNS-propagatie en afleveringsverificatievasthoudingen moeten worden behandeld als setupstatus, niet als bewijs dat de API-proxy of de homepage-documentatie kapot is.