Twórz przepływy pracy poczty agentów z zweryfikowanej domeny.

Pierwsze kroki

Beta osobista LoftBox zaczyna się od jednego adresu e-mail właściciela. Rejestracja tworzy organizację i wysyła e-mailem 6-cyfrowy token weryfikacyjny. Dopiero po weryfikacji adresu e-mail właściciela LoftBox zwraca pierwszy klucz API, a ten klucz w postaci jawnej jest pokazywany tylko raz. Weryfikacja wysyła również właścicielowi e-mail powitalny z limitami bety oraz przyszłą ścieżką rejestracji administracji/rozliczeń.

Konta bety osobistej są ograniczone do 100 wysyłek wychodzących dziennie. Domyślny okres przechowywania wiadomości w skrzynce wynosi 7 dni. Onboarding korporacyjny, rozliczenia, członkostwo w organizacji oraz wyższe limity to elementy planu rozwoju.

• POST /v1/auth/signupUtwórz organizację bety osobistej i wyślij token weryfikacyjny adresu e-mail właściciela.
• POST /v1/auth/signup/verifyZweryfikuj adres e-mail właściciela, otrzymaj jednorazowo początkowy klucz API i wyzwól powiadomienie powitalne dla właściciela.
• POST /v1/agentsUtwórz tożsamość agenta z właścicielem, przeznaczeniem i zakresem zasad.
• POST /v1/domainsRozpocznij onboarding domeny własnej dla domeny, którą kontrolujesz.
• POST /v1/agents/{agent_id}/mailboxesUtwórz skrzynkę pocztową beta zarządzaną przez LoftBox lub zweryfikowaną skrzynkę domeny własnej.
• POST /v1/messagesWysyłaj operacyjną pocztę e-mail ze skrzynki pocztowej agenta.
• GET /v1/mailboxes/{id}/inboxOdpytuj niepotwierdzone wiadomości przychodzące, gdy agent nie ma punktu końcowego webhooka.

Bazowy URL i dokumentacja maszynowo czytelna

Kanonicznym publicznym punktem końcowym API jest https://api.loftbox.net. Strona główna utrzymuje ścieżkę proxy /api/* do weryfikacji podglądu, ale integracje produkcyjne powinny używać dedykowanej nazwy hosta API.

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

Sprawdź edge i schemat przed podłączeniem integracji:

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

Trasa https://loftbox.net/api usuwa prefiks /api i przekazuje do tego samego źródła Fly API. Używaj jej do kontroli podglądu Pages, a nie jako głównego URL integracji.

Uwierzytelnianie API

Zacznij od zarejestrowania adresu e-mail właściciela dla organizacji bety osobistej. Właściciel otrzymuje token weryfikacyjny e-mailem; wywołanie weryfikacji zwraca jednorazowo początkowy klucz API i wysyła powiadomienie powitalne dla właściciela.

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

Użyj zwróconego serwerowego klucza API z nagłówkiem Authorization . Nigdy nie ujawniaj kluczy API w przeglądarkach, klientach mobilnych, publicznych logach ani zdarzeniach analitycznych.

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

Przechowuj klucze w serwerowym magazynie sekretów, takim jak Fly secrets, zmienne środowiskowe zarządzane przez platformę wdrożeniową lub dedykowany menedżer sekretów. Nie wklejaj prawdziwych kluczy do komentarzy zgłoszeń, zrzutów ekranu, narzędzi analitycznych ani kodu przeglądarki.

Rotuj klucze, gdy operator odchodzi, sekret mógł wyciec lub gdy środowisko nie potrzebuje już dostępu do API.

Instalacja jedną linią i prompt agenta

Agenci mogą zainstalować publiczne umiejętności poczty LoftBox, a następnie uruchomić przepływ onboardingu tylko z adresem e-mail właściciela. Umiejętność rejestracji wyprowadza etykietę organizacji, stabilny external_id, slug agenta oraz część lokalną skrzynki pocztowej z bieżącego agenta. Po rejestracji zainstalowane umiejętności wysyłania i sprawdzania skrzynki używają wydanego klucza API oraz identyfikatora skrzynki pocztowej.

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

Używaj sprawdzania aktualizacji wyłącznie jako ścieżki powiadomień. Instalacja nowego pakietu umiejętności zmienia zachowanie agenta, więc aktualizacje powinny być uruchamiane po zatwierdzeniu przez operatora.

Proś o inną wartość tylko wtedy, gdy nie można wyprowadzić tożsamości agenta lub gdy zduplikowany zewnętrzny identyfikator należy do innego agenta.

Onboarding domeny własnej

Każda domena wychodząca musi zostać zweryfikowana, zanim skrzynki pocztowe będą mogły z niej korzystać. API zwraca rekordy DNS potrzebne do potwierdzenia własności, routingu przychodzącego, wyrównania nadawcy oraz weryfikacji dostarczania.

1. Utwórz domenę za pomocą POST /v1/domains.
2. Pobierz wymagane rekordy za pomocą GET /v1/domains/{id}/dns.
3. Dodaj zwrócone rekordy TXT, MX, DKIM oraz return-path u swojego dostawcy DNS.
4. Wywołaj POST /v1/domains/{id}/verify po propagacji DNS.
5. Poczekaj, aż status przychodzący i wychodzący będą zweryfikowane, zanim utworzysz produkcyjne skrzynki pocztowe.

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"

Albo pozwól agentowi przeprowadzić cały onboarding biznesowy od początku do końca za pomocą ujednoliconego przepływu onboard-business-domain (uwierzytelnianie e-mail → onboarding domeny → DNS). Wklej ten prompt do swojego agenta:

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.

Oficjalne umiejętności & źródło

onboard-business-domain oraz setup-loftbox-domain to oficjalne umiejętności LoftBox. Są publikowane w publicznym repozytorium umiejętności i instalowane przez https://loftbox.net/install.sh — jeśli agent nie może ich znaleźć, jego zainstalowany pakiet jest nieaktualny, a ponowne uruchomienie instalatora je dodaje.

• Repozytorium (publiczne): github.com/TheMagicTower/loftbox-agent-mail-skill
• Katalogi umiejętności: onboard-business-domain/, setup-loftbox-domain/
• Wersja zainstalowanego pakietu & przypięty commit: loftbox.net/skill-version.json

Umiejętność setup-loftbox-domain jest wywoływana przez bezpośrednie uruchomienie jej skryptu (instalator nie tworzy polecenia powłoki setup-loftbox-domain ). $SKILL_DIR to miejsce, w którym install.sh umieścił umiejętność — np. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, lub na Hermesie ~/.hermes/skills/email/setup-loftbox-domain. Umiejętność wywołuje API LoftBox — używaj dokładnie tych wartości DNS, które zwraca API, nigdy ich nie zmyślaj:

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 orkiestruje register-loftbox-mail-agent (uwierzytelnianie e-mail) oraz setup-loftbox-domain (onboarding domeny + DNS) od początku do końca. Krok 6-cyfrowego tokena e-mail wymaga człowieka, więc nie jest w pełni bezobsługowy.

Na potrzeby startu beta osobista korzysta z dostarczania zarządzanego przez LoftBox oraz obsługi przychodzącego MX zarządzanej przez LoftBox. Domeny własne są włączane dopiero po weryfikacji.

Agenci i skrzynki pocztowe

Agenci posiadają przeznaczenie biznesowe, kontekst własności oraz stabilny zewnętrzny identyfikator. Skrzynki pocztowe dołączają adres i domenę do tego agenta. Utrzymuj nazwy wyświetlane, właścicieli oraz zakres zasad na tyle czytelne, by umożliwić przegląd przez operatora.

• Używaj jednej skrzynki pocztowej na agenta operacyjnego lub rolę w przepływie pracy.
• Używaj external_id do kontroli duplikatów oraz idempotentnej konfiguracji agenta.
• Używaj zweryfikowanych domen własnych do produkcyjnej poczty wychodzącej.
• Wyłącz lub wstrzymaj autonomiczne wysyłki, gdy przeznaczenie agenta jest niejasne.

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

Pomiń domain_id dla domeny bety osobistej zarządzanej przez LoftBox. Zarejestruj webhook agenta oddzielnie, jeśli agent ma punkt końcowy HTTPS.

Na zweryfikowanej domenie własnej możesz oznaczyć jedną skrzynkę jako catch-all ("is_catch_all": true przy tworzeniu lub aktualizacji). Każdy adres w tej domenie bez dokładnej skrzynki zostanie wtedy skierowany do niej — przydatne do przechwytywania support@, sales@, lub anything@twojadomena za pomocą jednego agenta.

Wysyłanie wiadomości

Wysyłaj wiadomości operacyjne lub transakcyjne przez API ze zweryfikowanej skrzynki pocztowej. LoftBox rejestruje referencje dostarczania, stan dostarczania, decyzje dotyczące limitów szybkości oraz wyniki zatwierdzeń operatora.

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

Przekaż send_at (RFC3339, w przyszłości), aby zaplanować dostarczanie, oraz nagłówek Idempotency-Key do deduplikacji ponownych prób (powtórka zwraca oryginalną wiadomość). Listuj i przeszukuj wysłane lub odebrane wiadomości za pomocą GET /v1/messages?q=<text>&label=<name>, i organizuj wątki przez POST/DELETE /v1/messages/{id}/labels.

LoftBox nie jest masowym nadawcą marketingowym. Zakupione listy, scrapowani odbiorcy oraz ogólne korzystanie z relayu SMTP są poza zakresem zasad MVP.

Webhooki przychodzące i odpytywanie

Odpowiedzi są przechowywane jako wiadomości przychodzące. Agenci z punktem końcowym HTTPS mogą odbierać podpisane zdarzenia webhooka; agenci bez niego powinni odpytywać skrzynkę odbiorczą i potwierdzać każdą przetworzoną wiadomość.

• message.inboundNowa wiadomość przychodząca lub odpowiedź została przeanalizowana, powiązana w wątek i udostępniona skonfigurowanemu webhookowi.
• message.deliveredZgłoszono dostarczenie do odbiorcy.
• message.failedDostarczenie wychodzące zakończyło się trwałym niepowodzeniem lub wyczerpało obsługę ponownych prób.

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

Sekret webhooka jest zwracany jednorazowo przy tworzeniu webhooka. Zapisz go natychmiast i weryfikuj każdy podpis przychodzący przed zaufaniem treści zdarzenia.

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

Potwierdzaj dopiero po trwałym przetworzeniu wiadomości przez agenta. Odpytywanie pustej skrzynki powinno stosować wycofywanie; aktywne odpytywanie powinno używać umiarkowanego interwału, takiego jak 30-60 sekund.

Strumieniowanie w czasie rzeczywistym (WebSocket)

Agenci, którzy nie mogą hostować webhooka HTTPS (na przykład działający za NAT lub zaporą), mogą subskrybować zdarzenia w czasie rzeczywistym przez WebSocket. Strumień przenosi te same typy zdarzeń co webhooki, z dostarczaniem poniżej sekundy i odtwarzaniem zdarzeń opartym na kursorze, które pominięto podczas rozłączenia. Wymaga zakresu receive .

• GET /v1/wsUaktualnienie WebSocket. Uwierzytelnij za pomocą Authorization: Bearer. Filtruj za pomocą ?event_types= oraz ?agent_id=; wznów za pomocą ?after=<cursor>.
• GET /v1/ws/asyncapi.jsonSpecyfikacja AsyncAPI dla strumienia (publiczna).

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

Przy ramce error z kodem lagged lub resync_required, połącz się ponownie, używając ostatnio otrzymanego kursora.

Uprawnienia i klucze API

Klucze API niosą zakresy. Zakresy ogólne (send, receive, admin) implikują zakresy szczegółowe (message:send, message:read, domain:manage, approval:decide, keys:manage, …), więc istniejące klucze nadal działają, podczas gdy możesz wydawać klucze potomne o najmniejszych uprawnieniach dla podagentów.

• POST /v1/auth/keysWydaj klucz potomny. Żądane zakresy muszą być podzbiorem zakresów wywołującego (brak eskalacji uprawnień). Opcjonalnie expires_in_days. Klucz w postaci jawnej zwracany jednorazowo.
• GET /v1/auth/keysListuj klucze organizacji (tylko metadane, bez sekretów). Wymaga keys:manage.
• DELETE /v1/auth/keys/{id}Unieważnij klucz i wszystkich jego potomków (kaskadowo). Dozwolone dla keys:manage lub rodzica klucza.

Zbiorcze raporty DMARC

Dostawcy skrzynek pocztowych (Gmail, Outlook, Yahoo, …) wysyłają codzienne zbiorcze raporty DMARC (rua) podsumowujące, które źródłowe adresy IP wysyłały pocztę jako Twoje zweryfikowane domeny oraz czy SPF/DKIM/DMARC były wyrównane. LoftBox przetwarza je na ustrukturyzowane raporty, dzięki czemu możesz monitorować dostarczalność i wykrywać podszywanie się. Każdy zapisany raport rejestruje również uwierzytelnioną domenę zgłaszającego.

• GET /v1/dmarc/reportsListuj zbiorcze raporty DMARC swojej organizacji, najnowsze jako pierwsze. Paginacja kursorowa przez before_date_end + before_id (zwracane razem jako next_cursor). Wymaga domain:read.
• GET /v1/dmarc/reports/{id}Pobierz jeden raport z jego rekordami dla każdego źródłowego IP (liczba wiadomości, dyspozycja, wyrównanie DKIM/SPF, header-from). Wymaga 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"

Raporty pojawiają się w miarę ich przesyłania przez dostawców (zwykle raz dziennie na zgłaszającego). Zwracane są tylko raporty dotyczące Twoich własnych zweryfikowanych domen; raporty platformowe lub niehostowanych domen nigdy nie są ujawniane.

Zdarzenia dostarczania

Status dostarczania jest znormalizowany w ramach zarządzanych wywołań zwrotnych dostarczania oraz wewnętrznego stanu wysyłki. Używaj identyfikatorów zdarzeń oraz referencji dostarczania do wsparcia, a nie prywatnych danych odbiorcy.

• queued: przyjęte przez LoftBox do dostarczenia.
• sent: przyjęte do dostarczenia wychodzącego.
• delivered: zgłoszono dostarczenie do odbiorcy.
• failed: dostarczenie zakończyło się trwałym niepowodzeniem lub wyczerpało ponowne próby.
• blocked: zasada, limit szybkości lub kontrola zgłoszeń zablokowała wysyłanie.

Limity szybkości i kontrola zgłoszeń

Wysyłanie wychodzące jest ograniczone zasadami organizacji, agenta, skrzynki pocztowej, odbiorcy i domeny. Organizacje bety osobistej są ograniczone do 100 wysyłek dziennie. Wiadomości wysokiego ryzyka mogą zostać wstrzymane do zatwierdzenia przed podjęciem próby dostarczenia.

Obsługuj odpowiedzi 429 poprzez wycofywanie. Nie ponawiaj prób w nieskończoność ani nie omijaj wstrzymań zatwierdzeń z innej skrzynki pocztowej.

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

Zarządzane dostarczanie i konfiguracja bezpieczeństwa

LoftBox obsługuje zarządzane dostarczanie wychodzące dla kont beta. Dokumentacja publiczna powinna opisywać kontrole widoczne dla klienta bez ujawniania wewnętrznych nazw dostawców, poświadczeń ani szczegółów routingu.

• Charakter działalności: zarządzane przez API operacyjne tożsamości e-mail dla agentów AI z zweryfikowaną domeną.
• Typy e-maili: powiadomienia transakcyjne/systemowe, odpowiedzi agentów inicjowane przez zweryfikowanych użytkowników, wiadomości onboardingowe/testowe oraz obsługa zgłoszeń/kontaktu.
• Kontrola: tylko zweryfikowane domeny, jawne limity szybkości, logi dostarczania, obsługa wykluczeń/skarg oraz monitorowany kontakt zgłoszeniowy.
• Strony publiczne: Prywatność, Regulamin, oraz Zasady antyspamowe.

Propagacja DNS oraz wstrzymania weryfikacji dostarczania powinny być traktowane jako stan konfiguracji, a nie jako dowód, że proxy API lub dokumentacja strony głównej są zepsute.