Crea flussi di lavoro email per agenti su domini verificati.

Per iniziare

La beta personale di LoftBox inizia con un'unica email del proprietario. La registrazione crea l'organizzazione e invia via email un token di verifica a 6 cifre. Solo dopo la verifica dell'email del proprietario LoftBox restituisce la prima chiave API, e quella chiave in chiaro viene mostrata una sola volta. La verifica invia inoltre al proprietario un'email di benvenuto con i limiti della beta e il futuro percorso di registrazione per amministrazione/fatturazione.

Gli account della beta personale sono limitati a 100 invii in uscita al giorno. La conservazione dei messaggi nella casella di posta è impostata per impostazione predefinita a 7 giorni. L'onboarding enterprise, la fatturazione, l'appartenenza all'organizzazione e limiti più elevati sono elementi della roadmap.

• POST /v1/auth/signupCrea un'organizzazione beta personale e invia il token di verifica dell'email del proprietario.
• POST /v1/auth/signup/verifyVerifica l'email del proprietario, ricevi una sola volta la chiave API iniziale e attiva l'avviso di benvenuto per il proprietario.
• POST /v1/agentsCrea un'identità dell'agente con proprietario, scopo e ambito di policy.
• POST /v1/domainsAvvia l'onboarding di un dominio personalizzato per un dominio che controlli.
• POST /v1/agents/{agent_id}/mailboxesCrea una casella di posta beta gestita da LoftBox o una casella di posta su dominio personalizzato verificato.
• POST /v1/messagesInvia email operative dalla casella di posta dell'agente.
• GET /v1/mailboxes/{id}/inboxEsegui il polling dei messaggi in entrata non confermati quando l'agente non ha un endpoint webhook.

Base URL e documentazione leggibile dalle macchine

L'endpoint pubblico canonico dell'API è https://api.loftbox.net. La homepage mantiene un /api/* percorso proxy per la verifica in anteprima, ma le integrazioni in produzione dovrebbero usare l'hostname API dedicato.

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

Controlla l'edge e lo schema prima di predisporre un'integrazione:

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

La https://loftbox.net/api route rimuove il prefisso /api e inoltra alla stessa origine API Fly. Usala per i controlli di anteprima di Pages, non come URL di integrazione principale.

Autenticazione API

Inizia registrando l'email del proprietario per l'organizzazione della beta personale. Il proprietario riceve un token di verifica via email; la chiamata di verifica restituisce una sola volta la chiave API iniziale e invia l'avviso di benvenuto al proprietario.

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

Usa la chiave API server-side restituita con l'header Authorization . Non esporre mai le chiavi API nei browser, nei client mobili, nei log pubblici o negli eventi di analytics.

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

Conserva le chiavi in un archivio di segreti server-side come i Fly secrets, le variabili d'ambiente gestite dalla piattaforma di deploy o un secret manager dedicato. Non incollare chiavi reali nei commenti delle issue, negli screenshot, negli strumenti di analytics o nel codice del browser.

Ruota le chiavi quando un operatore lascia il team, quando un segreto potrebbe essere trapelato o quando un ambiente non ha più bisogno dell'accesso API.

Installazione in una riga e prompt dell'agente

Gli agenti possono installare le skill di posta pubbliche di LoftBox, quindi eseguire il flusso di onboarding con la sola email del proprietario. La skill di registrazione deriva l'etichetta dell'organizzazione, lo external_idstabile, lo slug dell'agente e la parte locale della casella di posta dall'agente corrente. Dopo la registrazione, le skill di invio e di controllo della posta in entrata installate usano la chiave API emessa e l'ID della casella di posta.

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

Usa i controlli degli aggiornamenti solo come canale di notifica. L'installazione di un nuovo bundle di skill modifica il comportamento dell'agente, quindi gli aggiornamenti dovrebbero essere eseguiti dopo l'approvazione dell'operatore.

Chiedi un altro valore solo se l'identità dell'agente non può essere derivata o se un ID esterno duplicato appartiene a un agente diverso.

Onboarding di domini personalizzati

Ogni dominio in uscita deve essere verificato prima che le caselle di posta possano usarlo. L'API restituisce i record DNS necessari per la proprietà, il routing in entrata, l'allineamento del mittente e la verifica della consegna.

1. Crea il dominio con POST /v1/domains.
2. Recupera i record richiesti con GET /v1/domains/{id}/dns.
3. Aggiungi i record TXT, MX, DKIM e return-path restituiti presso il tuo host DNS.
4. Chiama POST /v1/domains/{id}/verify dopo la propagazione DNS.
5. Attendi che lo stato in entrata e in uscita siano entrambi verificati prima di creare caselle di posta di produzione.

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"

Oppure lascia che un agente guidi l'intero onboarding aziendale dall'inizio alla fine con il flusso unificato onboard-business-domain (autenticazione email → onboarding dominio → DNS). Incolla questo prompt nel tuo agente:

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 ufficiali & sorgente

onboard-business-domain e setup-loftbox-domain sono skill ufficiali di LoftBox. Sono pubblicate nel repository pubblico delle skill e installate da https://loftbox.net/install.sh — se un agente non riesce a trovarle, il suo bundle installato è obsoleto e rieseguendo l'installer le aggiunge.

• Repository (pubblico): github.com/TheMagicTower/loftbox-agent-mail-skill
• Directory delle skill: onboard-business-domain/, setup-loftbox-domain/
• Versione del bundle installato & commit fissato: loftbox.net/skill-version.json

La setup-loftbox-domain skill viene invocata eseguendo direttamente il suo script (l'installer non crea un comando shell setup-loftbox-domain ). $SKILL_DIR è ovunque install.sh abbia collocato la skill — ad esempio ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, o su Hermes ~/.hermes/skills/email/setup-loftbox-domain. La skill chiama l'API di LoftBox — usa esattamente i valori DNS che l'API restituisce, non inventarli mai:

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 orchestra register-loftbox-mail-agent (autenticazione email) e setup-loftbox-domain (onboarding dominio + DNS) dall'inizio alla fine. Il passaggio del token email a 6 cifre richiede un essere umano, quindi non è completamente automatizzato.

Per il lancio, la beta personale usa la consegna gestita da LoftBox e la gestione MX in entrata gestita da LoftBox. I domini personalizzati sono abilitati solo dopo la verifica.

Agenti e caselle di posta

Gli agenti detengono lo scopo aziendale, il contesto di proprietà e l'ID esterno stabile. Le caselle di posta associano un indirizzo e un dominio a quell'agente. Mantieni i nomi visualizzati, i proprietari e l'ambito di policy abbastanza chiari per la revisione dell'operatore.

• Usa una casella di posta per ogni agente operativo o ruolo del flusso di lavoro.
• Usa external_id per i controlli dei duplicati e la configurazione idempotente dell'agente.
• Usa domini personalizzati verificati per la posta in uscita di produzione.
• Disabilita o trattieni gli invii autonomi quando lo scopo dell'agente non è chiaro.

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

Ometti domain_id per il dominio della beta personale gestito da LoftBox. Registra separatamente un webhook dell'agente se l'agente ha un endpoint HTTPS.

Su un dominio personalizzato verificato puoi contrassegnare una casella di posta come catch-all ("is_catch_all": true alla creazione o all'aggiornamento). Qualsiasi indirizzo di quel dominio senza una casella di posta esatta viene quindi instradato ad essa — utile per catturare support@, sales@, o anything@yourdomain con un singolo agente.

Invio dei messaggi

Invia messaggi operativi o transazionali tramite l'API da una casella di posta verificata. LoftBox registra i riferimenti di consegna, lo stato di consegna, le decisioni sui limiti di frequenza e gli esiti delle approvazioni dell'operatore.

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

Passa send_at (RFC3339, futuro) per pianificare la consegna, e un header Idempotency-Key per deduplicare i tentativi (un replay restituisce il messaggio originale). Elenca e cerca i messaggi inviati o ricevuti con GET /v1/messages?q=<text>&label=<name>, e organizza i thread tramite POST/DELETE /v1/messages/{id}/labels.

LoftBox non è un servizio di invio massivo per marketing. Liste acquistate, destinatari raccolti tramite scraping e l'uso come relay SMTP generico sono al di fuori della policy dell'MVP.

Webhook in entrata e polling

Le risposte vengono memorizzate come messaggi in entrata. Gli agenti con un endpoint HTTPS possono ricevere eventi webhook firmati; gli agenti che non ne hanno uno dovrebbero eseguire il polling della casella di posta in entrata e confermare ogni messaggio elaborato.

• message.inboundUn nuovo messaggio in entrata o una risposta è stato analizzato, organizzato in thread e reso disponibile al webhook configurato.
• message.deliveredLa consegna è stata segnalata per il destinatario.
• message.failedLa consegna in uscita è fallita in modo permanente o ha esaurito la gestione dei tentativi.

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

Il segreto del webhook viene restituito una sola volta alla creazione del webhook. Conservalo immediatamente e verifica ogni firma in entrata prima di fidarti del contenuto dell'evento.

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

Conferma solo dopo che l'agente ha elaborato il messaggio in modo durevole. Il polling di una casella di posta vuota dovrebbe applicare un backoff; il polling attivo dovrebbe usare un intervallo moderato come 30-60 secondi.

Streaming in tempo reale (WebSocket)

Gli agenti che non possono ospitare un webhook HTTPS (ad esempio, quelli in esecuzione dietro NAT o firewall) possono sottoscriversi agli eventi in tempo reale tramite un WebSocket. Lo stream trasporta gli stessi tipi di evento dei webhook, con consegna inferiore al secondo e replay basato su cursore degli eventi persi durante la disconnessione. Richiede lo scope receive .

• GET /v1/wsUpgrade WebSocket. Autenticati con Authorization: Bearer. Filtra con ?event_types= e ?agent_id=; riprendi con ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonSpecifica AsyncAPI per lo stream (pubblica).

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

Su un error frame con codice lagged o resync_required, riconnettiti usando l'ultimo cursore ricevuto.

Permessi e chiavi API

Le chiavi API portano degli scope. Gli scope generici (send, receive, admin) implicano scope a grana fine (message:send, message:read, domain:manage, approval:decide, keys:manage, …), quindi le chiavi esistenti continuano a funzionare mentre puoi emettere chiavi figlie con privilegi minimi per i sub-agenti.

• POST /v1/auth/keysEmetti una chiave figlia. Gli scope richiesti devono essere un sottoinsieme di quelli del chiamante (nessuna escalation di privilegi). Opzionale expires_in_days. Chiave in chiaro restituita una sola volta.
• GET /v1/auth/keysElenca le chiavi dell'organizzazione (solo metadati, nessun segreto). Richiede keys:manage.
• DELETE /v1/auth/keys/{id}Revoca una chiave e tutti i suoi discendenti (a cascata). Consentito per keys:manage o per il genitore della chiave.

Report aggregati DMARC

I provider di caselle di posta (Gmail, Outlook, Yahoo, …) inviano quotidianamente report aggregati DMARC (rua) che riepilogano quali IP di origine hanno inviato posta come i tuoi domini verificati e se SPF/DKIM/DMARC erano allineati. LoftBox li acquisisce in report strutturati così puoi monitorare la deliverability e individuare lo spoofing. Ogni report memorizzato registra anche il dominio del reporter autenticato.

• GET /v1/dmarc/reportsElenca i report aggregati DMARC della tua organizzazione, dal più recente. Paginazione con cursore tramite before_date_end + before_id (restituiti insieme come next_cursor). Richiede domain:read.
• GET /v1/dmarc/reports/{id}Recupera un report con i suoi record per singolo IP di origine (conteggio messaggi, disposizione, allineamento DKIM/SPF, header-from). Richiede 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"

I report compaiono man mano che i provider li inviano (tipicamente una volta al giorno per reporter). Vengono restituiti solo i report per i tuoi domini verificati; i report della piattaforma o di domini non ospitati non vengono mai esposti.

Eventi di consegna

Lo stato di consegna è normalizzato tra i callback di consegna gestita e lo stato di invio interno. Usa gli ID degli eventi e i riferimenti di consegna per il supporto, non i dati privati dei destinatari.

• queued: accettato da LoftBox per la consegna.
• sent: accettato per la consegna in uscita.
• delivered: la consegna è stata segnalata per il destinatario.
• failed: la consegna è fallita in modo permanente o ha esaurito i tentativi.
• blocked: policy, limite di frequenza o controllo di report hanno bloccato l'invio.

Limiti di frequenza e controlli di report

L'invio in uscita è limitato dalle policy di organizzazione, agente, casella di posta, destinatario e dominio. Le organizzazioni della beta personale hanno un tetto di 100 invii al giorno. I messaggi ad alto rischio possono essere trattenuti per l'approvazione prima che venga tentata la consegna.

Gestisci le risposte 429 applicando un backoff. Non ritentare indefinitamente né aggirare i blocchi di approvazione da un'altra casella di posta.

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

Consegna gestita e configurazione di sicurezza

LoftBox gestisce la consegna in uscita per gli account beta. La documentazione pubblica dovrebbe descrivere i controlli visibili al cliente senza esporre nomi di vendor interni, credenziali o dettagli di routing.

• Natura aziendale: identità email operative gestite via API per agenti AI su domini verificati.
• Tipi di email: notifiche transazionali/di sistema, risposte degli agenti avviate da utenti verificati, messaggi di onboarding/test e gestione di report/contatti.
• Controlli: solo domini verificati, limiti di frequenza espliciti, log di consegna, gestione di soppressione/reclami e contatto di report monitorato.
• Pagine pubbliche: Privacy, Termini, e Policy anti-spam.

I blocchi per propagazione DNS e verifica della consegna dovrebbero essere considerati uno stato di configurazione, non una prova che il proxy API o la documentazione della homepage siano malfunzionanti.