Documentation de l'API bêta

Concevez des workflows e-mail d'agents à domaine vérifié.

Cette documentation bêta couvre la vérification de l'e-mail du propriétaire, l'authentification API, la configuration des compétences d'agent, l'intégration de domaines personnalisés, les boîtes aux lettres d'agent, l'envoi, les webhooks entrants, les événements de remise, les limites de débit et les contrôles de remise.

Démarrer

Premiers pas

La bêta personnelle de LoftBox commence par un e-mail de propriétaire unique. L'inscription crée l'organisation et envoie par e-mail un token de vérification à 6 chiffres. Ce n'est qu'après la vérification de l'e-mail du propriétaire que LoftBox renvoie la première clé API, et cette clé en clair n'est affichée qu'une seule fois. La vérification envoie également au propriétaire un e-mail de bienvenue indiquant les limites de la bêta et le futur parcours d'inscription admin/facturation.

Les comptes de la bêta personnelle sont limités à 100 envois sortants par jour. La conservation des messages des boîtes aux lettres est par défaut de 7 jours. L'intégration entreprise, la facturation, l'appartenance à une organisation et des limites plus élevées figurent dans la feuille de route.

  • POST /v1/auth/signupCrée une organisation de bêta personnelle et envoie le token de vérification de l'e-mail du propriétaire.
  • POST /v1/auth/signup/verifyVérifie l'e-mail du propriétaire, reçoit la clé API initiale une seule fois et déclenche l'avis de bienvenue du propriétaire.
  • POST /v1/agentsCrée une identité d'agent avec propriétaire, objectif et portée de politique.
  • POST /v1/domainsDémarre l'intégration de domaine personnalisé pour un domaine que vous contrôlez.
  • POST /v1/agents/{agent_id}/mailboxesCrée une boîte aux lettres bêta gérée par LoftBox ou une boîte aux lettres à domaine personnalisé vérifié.
  • POST /v1/messagesEnvoie un e-mail opérationnel depuis la boîte aux lettres de l'agent.
  • GET /v1/mailboxes/{id}/inboxInterroge les messages entrants non acquittés lorsque l'agent ne dispose pas d'endpoint webhook.
Endpoint

URL de base et documentation lisible par machine

L'endpoint public canonique de l'API est https://api.loftbox.net. La page d'accueil conserve un /api/* chemin proxy pour la vérification d'aperçu, mais les intégrations de production doivent utiliser le nom d'hôte API dédié.

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

Vérifiez l'edge et le schéma avant de câbler une intégration :

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

La route https://loftbox.net/api supprime le préfixe /api et transmet vers la même origine de l'API Fly. Utilisez-la pour les vérifications d'aperçu Pages, pas comme URL d'intégration principale.

Authentification

Authentification API

Commencez par enregistrer l'e-mail du propriétaire pour l'organisation de bêta personnelle. Le propriétaire reçoit un token de vérification par e-mail ; l'appel de vérification renvoie la clé API initiale une seule fois et envoie l'avis de bienvenue au propriétaire.

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

Utilisez la clé API côté serveur renvoyée avec l'en-tête Authorization . N'exposez jamais les clés API dans les navigateurs, les clients mobiles, les journaux publics ou les événements d'analytics.

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

Stockez les clés dans un coffre de secrets côté serveur tel que les secrets Fly, des variables d'environnement gérées par la plateforme de déploiement ou un gestionnaire de secrets dédié. Ne collez pas de clés réelles dans les commentaires de tickets, les captures d'écran, les outils d'analytics ou le code de navigateur.

Faites tourner les clés lorsqu'un opérateur quitte l'équipe, qu'un secret a pu fuiter ou qu'un environnement n'a plus besoin d'accès à l'API.

Configuration de l'agent

Installation en une ligne et prompt d'agent

Les agents peuvent installer les compétences mail publiques de LoftBox, puis exécuter le flux d'intégration uniquement avec l'e-mail du propriétaire. La compétence d'enregistrement dérive le libellé de l'organisation, l' external_idstable, le slug de l'agent et la partie locale de la boîte aux lettres à partir de l'agent actuel. Après l'enregistrement, les compétences d'envoi et de consultation de boîte de réception installées utilisent la clé API émise et l'ID de boîte aux lettres.

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

Utilisez les vérifications de mises à jour uniquement comme canal de notification. L'installation d'un nouveau bundle de compétences modifie le comportement de l'agent ; les mises à jour doivent donc être exécutées après approbation de l'opérateur.

Ne demandez une autre valeur que si l'identité de l'agent ne peut pas être dérivée ou qu'un ID externe en double appartient à un autre agent.

Domaines

Intégration de domaine personnalisé

Chaque domaine sortant doit être vérifié avant que les boîtes aux lettres puissent l'utiliser. L'API renvoie les enregistrements DNS nécessaires à la preuve de propriété, au routage entrant, à l'alignement de l'expéditeur et à la vérification de la remise.

  1. Créez le domaine avec POST /v1/domains.
  2. Récupérez les enregistrements requis avec GET /v1/domains/{id}/dns.
  3. Ajoutez les enregistrements TXT, MX, DKIM et return-path renvoyés chez votre hébergeur DNS.
  4. Appelez POST /v1/domains/{id}/verify après la propagation DNS.
  5. Attendez que les statuts entrant et sortant soient tous deux vérifiés avant de créer des boîtes aux lettres de production.
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"

Ou laissez un agent piloter de bout en bout l'intégration complète de l'entreprise avec le flux unifié onboard-business-domain (authentification e-mail → intégration du domaine → DNS). Collez ce prompt dans votre 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.

Compétences officielles &amp; source

onboard-business-domain et setup-loftbox-domain sont des compétences officielles LoftBox. Elles sont publiées dans le dépôt public de compétences et installées par https://loftbox.net/install.sh &mdash; si un agent ne les trouve pas, son bundle installé est obsolète et réexécuter l'installateur les ajoute.

La compétence setup-loftbox-domain est invoquée en exécutant son script directement (l'installateur ne crée pas de setup-loftbox-domain commande shell). $SKILL_DIR correspond à l'endroit où install.sh a placé la compétence &mdash; par ex. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, ou sur Hermes ~/.hermes/skills/email/setup-loftbox-domain. La compétence appelle l'API LoftBox &mdash; utilisez exactement les valeurs DNS que l'API renvoie, ne les inventez jamais :

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 orchestre register-loftbox-mail-agent (authentification e-mail) et setup-loftbox-domain (intégration du domaine + DNS) de bout en bout. L'étape du token e-mail à 6 chiffres requiert un humain ; elle n'est donc pas entièrement automatisée.

Pour le lancement, la bêta personnelle utilise une remise gérée par LoftBox et une gestion MX entrante gérée par LoftBox. Les domaines personnalisés ne sont activés qu'après vérification.

Boîtes aux lettres

Agents et boîtes aux lettres

Les agents portent l'objectif métier, le contexte de propriété et l'ID externe stable. Les boîtes aux lettres rattachent une adresse et un domaine à cet agent. Gardez les noms d'affichage, les propriétaires et la portée de politique suffisamment clairs pour la revue par l'opérateur.

  • Utilisez une boîte aux lettres par agent opérationnel ou rôle de workflow.
  • Utilisez external_id pour les vérifications de doublons et la configuration idempotente de l'agent.
  • Utilisez des domaines personnalisés vérifiés pour le courrier sortant de production.
  • Désactivez ou suspendez les envois autonomes lorsque l'objectif de l'agent n'est pas clair.
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
  }'

Omettez domain_id pour le domaine de bêta personnelle géré par LoftBox. Enregistrez séparément un webhook d'agent si l'agent dispose d'un endpoint HTTPS.

Sur un domaine personnalisé vérifié, vous pouvez marquer une boîte aux lettres comme catch-all ("is_catch_all": true à la création ou à la mise à jour). Toute adresse de ce domaine sans boîte aux lettres exacte y est alors routée — utile pour capturer support@, sales@, ou anything@yourdomain avec un seul agent.

Sortant

Envoi de messages

Envoyez des messages opérationnels ou transactionnels via l'API depuis une boîte aux lettres vérifiée. LoftBox enregistre les références de remise, l'état de remise, les décisions de limitation de débit et les résultats d'approbation par l'opérateur.

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

Passez send_at (RFC3339, futur) pour planifier la remise, et un en-tête Idempotency-Key pour dédupliquer les nouvelles tentatives (un rejeu renvoie le message original). Listez et recherchez les messages envoyés ou reçus avec GET /v1/messages?q=<text>&label=<name>, et organisez les fils via POST/DELETE /v1/messages/{id}/labels.

LoftBox n'est pas un outil d'envoi marketing de masse. Les listes achetées, les destinataires extraits par scraping et l'usage de relais SMTP générique sont en dehors de la politique du MVP.

Entrant

Webhooks entrants et polling

Les réponses sont stockées comme messages entrants. Les agents disposant d'un endpoint HTTPS peuvent recevoir des événements webhook signés ; les agents qui n'en ont pas devraient interroger la boîte de réception de la boîte aux lettres et acquitter chaque message traité.

  • message.inboundUn nouveau message entrant ou une réponse a été analysé, regroupé en fil et mis à disposition du webhook configuré.
  • message.deliveredLa remise a été signalée pour le destinataire.
  • message.failedLa remise sortante a échoué définitivement ou a épuisé la gestion des nouvelles tentatives.
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"
    ]
  }'

Le secret du webhook est renvoyé une seule fois lors de la création du webhook. Stockez-le immédiatement et vérifiez chaque signature entrante avant de faire confiance au contenu de l'événement.

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

N'acquittez qu'après que l'agent a traité durablement le message. Le polling d'une boîte de réception vide devrait appliquer un back-off ; le polling actif devrait utiliser un intervalle modéré, par exemple 30 à 60 secondes.

Entrant

Streaming en temps réel (WebSocket)

Les agents qui ne peuvent pas héberger de webhook HTTPS (par exemple, fonctionnant derrière un NAT ou un firewall) peuvent s'abonner aux événements en temps réel via un WebSocket. Le flux transporte les mêmes types d'événements que les webhooks, avec une remise en moins d'une seconde et un rejeu basé sur cursor des événements manqués pendant la déconnexion. Nécessite la portée receive .

  • GET /v1/wsMise à niveau WebSocket. Authentifiez-vous avec Authorization: Bearer. Filtrez avec ?event_types= et ?agent_id=; reprenez avec ?after=<cursor>.
  • GET /v1/ws/asyncapi.jsonSpécification AsyncAPI du flux (publique).
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

Sur une frame error avec le code lagged ou resync_required, reconnectez-vous en utilisant le dernier cursor reçu.

Contrôle d'accès

Permissions et clés API

Les clés API portent des portées. Les portées larges (send, receive, admin) impliquent des portées fines (message:send, message:read, domain:manage, approval:decide, keys:manage, …), de sorte que les clés existantes continuent de fonctionner tout en vous permettant d'émettre des clés enfants à moindre privilège pour les sous-agents.

  • POST /v1/auth/keysÉmet une clé enfant. Les portées demandées doivent être un sous-ensemble de celles de l'appelant (pas d'escalade de privilèges). Optionnel expires_in_days. Clé en clair renvoyée une seule fois.
  • GET /v1/auth/keysListe les clés de l'organisation (métadonnées uniquement, aucun secret). Nécessite keys:manage.
  • DELETE /v1/auth/keys/{id}Révoque une clé et tous ses descendants (en cascade). Autorisé pour keys:manage ou le parent de la clé.
DMARC

Rapports agrégés DMARC

Les fournisseurs de boîtes aux lettres (Gmail, Outlook, Yahoo, …) envoient quotidiennement des rapports agrégés DMARC (rua) résumant quelles adresses IP source ont envoyé du courrier en tant que vos domaines vérifiés et si SPF/DKIM/DMARC étaient alignés. LoftBox les ingère dans des rapports structurés afin que vous puissiez surveiller la délivrabilité et détecter l'usurpation. Chaque rapport stocké enregistre également le domaine du déclarant authentifié.

  • GET /v1/dmarc/reportsListe les rapports agrégés DMARC de votre organisation, du plus récent au plus ancien. Pagination par cursor via before_date_end + before_id (renvoyés ensemble sous next_cursor). Nécessite domain:read.
  • GET /v1/dmarc/reports/{id}Récupère un rapport avec ses enregistrements par adresse IP source (nombre de messages, disposition, alignement DKIM/SPF, header-from). Nécessite 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"

Les rapports apparaissent à mesure que les fournisseurs les soumettent (généralement une fois par jour et par déclarant). Seuls les rapports concernant vos propres domaines vérifiés sont renvoyés ; les rapports de plateforme ou de domaines non hébergés ne sont jamais exposés.

Événements

Événements de remise

Le statut de remise est normalisé entre les callbacks de remise gérée et l'état d'envoi interne. Utilisez les ID d'événement et les références de remise pour le support, et non les données privées des destinataires.

  • queued : accepté par LoftBox pour remise.
  • sent : accepté pour remise sortante.
  • delivered : la remise a été signalée pour le destinataire.
  • failed : la remise a échoué définitivement ou a épuisé les nouvelles tentatives.
  • blocked : une politique, une limite de débit ou un contrôle de rapport a bloqué l'envoi.
Contrôles

Limites de débit et contrôles de rapport

L'envoi sortant est limité par les politiques d'organisation, d'agent, de boîte aux lettres, de destinataire et de domaine. Les organisations de bêta personnelle sont plafonnées à 100 envois par jour. Les messages à haut risque peuvent être suspendus pour approbation avant qu'une remise ne soit tentée.

Gérez les réponses 429 en appliquant un back-off. Ne réessayez pas indéfiniment et ne contournez pas les suspensions pour approbation depuis une autre boîte aux lettres.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Contrôles de remise

Remise gérée et configuration de sécurité

LoftBox exploite une remise sortante gérée pour les comptes bêta. La documentation publique doit décrire les contrôles visibles par le client sans exposer les noms de fournisseurs internes, les identifiants ou les détails de routage.

  • Nature de l'activité : identités e-mail opérationnelles gérées par API pour des agents IA à domaine vérifié.
  • Types d'e-mails : notifications transactionnelles/système, réponses d'agent initiées par des utilisateurs vérifiés, messages d'intégration/de test, et gestion des rapports/contacts.
  • Contrôles : domaines vérifiés uniquement, limites de débit explicites, journaux de remise, gestion des suppressions/plaintes, et contact de rapport surveillé.
  • Pages publiques : Confidentialité, Conditions, et Politique anti-spam.

La propagation DNS et les suspensions de vérification de remise doivent être considérées comme un état de configuration, et non comme la preuve que le proxy de l'API ou la documentation de la page d'accueil sont défaillants.