검증된 도메인 기반 에이전트 이메일 워크플로를 구축하세요.

시작하기

LoftBox 개인 베타는 하나의 소유자 이메일로 시작합니다. 가입하면 조직이 생성되고 6자리 검증 토큰이 이메일로 발송됩니다. 소유자 이메일을 검증한 후에야 LoftBox는 첫 API 키를 반환하며, 이 평문 키는 한 번만 표시됩니다. 검증 시 소유자에게 베타 한도와 향후 관리자/결제 가입 경로가 담긴 환영 이메일도 함께 발송됩니다.

개인 베타 계정은 하루 100건의 아웃바운드 발송으로 제한됩니다. 메일박스 메시지 보관 기간은 기본 7일입니다. 엔터프라이즈 온보딩, 결제, 조직 멤버십, 더 큰 한도는 로드맵 항목입니다.

• POST /v1/auth/signup개인 베타 조직을 생성하고 소유자 이메일 검증 토큰을 발송합니다.
• POST /v1/auth/signup/verify소유자 이메일을 검증하고 초기 API 키를 한 번 받으며 소유자 환영 안내를 트리거합니다.
• POST /v1/agents소유자, 목적, 정책 범위를 갖춘 에이전트 아이덴티티를 생성합니다.
• POST /v1/domains직접 관리하는 도메인에 대해 커스텀 도메인 온보딩을 시작합니다.
• POST /v1/agents/{agent_id}/mailboxesLoftBox 관리형 베타 메일박스 또는 검증된 커스텀 도메인 메일박스를 생성합니다.
• POST /v1/messages에이전트 메일박스에서 운영 이메일을 발송합니다.
• GET /v1/mailboxes/{id}/inbox에이전트에 webhook endpoint가 없을 때 확인되지 않은 인바운드 메시지를 폴링합니다.

Base URL과 기계 판독용 문서

표준 공개 API endpoint는 https://api.loftbox.net입니다. 홈페이지는 미리보기 검증을 위해 /api/* 프록시 경로를 유지하지만, 프로덕션 통합에서는 전용 API 호스트명을 사용해야 합니다.

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

통합을 연결하기 전에 엣지와 스키마를 확인하세요:

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

이 https://loftbox.net/api 경로는 /api 접두사를 제거하고 동일한 Fly API origin으로 전달합니다. 기본 통합 URL이 아닌 Pages 미리보기 확인용으로 사용하세요.

API 인증

먼저 개인 베타 조직에 소유자 이메일을 등록하세요. 소유자는 검증 토큰을 이메일로 받으며, 검증 호출은 초기 API 키를 한 번 반환하고 소유자 환영 안내를 발송합니다.

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

반환된 서버 측 API 키를 Authorization 헤더와 함께 사용하세요. 브라우저, 모바일 클라이언트, 공개 로그, 분석 이벤트에 API 키를 절대 노출하지 마세요.

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

Fly secrets, 배포 플랫폼이 관리하는 환경 변수, 전용 secret manager 등 서버 측 시크릿 저장소에 키를 보관하세요. 실제 키를 이슈 코멘트, 스크린샷, 분석 도구, 브라우저 코드에 붙여넣지 마세요.

운영자가 떠나거나, 시크릿이 유출되었을 수 있거나, 환경에서 더 이상 API 접근이 필요하지 않을 때 키를 회전하세요.

한 줄 설치와 에이전트 프롬프트

에이전트는 공개 LoftBox 메일 스킬을 설치한 뒤, 소유자 이메일만으로 온보딩 흐름을 실행할 수 있습니다. 등록 스킬은 현재 에이전트로부터 조직 라벨, 안정적인 external_id, 에이전트 슬러그, 메일박스 로컬 파트를 도출합니다. 등록 후 설치된 발송 및 inbox 확인 스킬은 발급된 API 키와 메일박스 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

업데이트 확인은 알림 경로로만 사용하세요. 새 스킬 번들을 설치하면 에이전트 동작이 바뀌므로, 업데이트는 운영자 승인 후에 실행해야 합니다.

에이전트 아이덴티티를 도출할 수 없거나 중복된 외부 ID가 다른 에이전트에 속한 경우에만 다른 값을 요청하세요.

커스텀 도메인 온보딩

모든 아웃바운드 도메인은 메일박스가 사용하기 전에 검증되어야 합니다. API는 소유권, 인바운드 라우팅, 발신자 정렬, 전송 검증에 필요한 DNS 레코드를 반환합니다.

1. 도메인을 생성합니다: POST /v1/domains.
2. 필수 레코드를 조회합니다: GET /v1/domains/{id}/dns.
3. 반환된 TXT, MX, DKIM, return-path 레코드를 DNS 호스트에 추가하세요.
4. 호출: POST /v1/domains/{id}/verify DNS 전파 후에 호출합니다.
5. 프로덕션 메일박스를 생성하기 전에 인바운드와 아웃바운드 상태가 모두 검증될 때까지 기다리세요.

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"

또는 에이전트가 통합된 onboard-business-domain 흐름(이메일 인증 → 도메인 온보드 → DNS)으로 전체 비즈니스 온보딩을 처음부터 끝까지 진행하도록 할 수 있습니다. 이 프롬프트를 에이전트에 붙여넣으세요:

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.

공식 스킬 & 소스

onboard-business-domain 와 setup-loftbox-domain 는 공식 LoftBox 스킬입니다. 공개 스킬 저장소에 게시되어 있으며 https://loftbox.net/install.sh — 에이전트가 이를 찾지 못하면 설치된 번들이 오래된 것이며 설치 프로그램을 다시 실행하면 추가됩니다.

• 저장소(공개): github.com/TheMagicTower/loftbox-agent-mail-skill
• 스킬 디렉터리: onboard-business-domain/, setup-loftbox-domain/
• 설치된 번들 버전 & 고정 커밋: loftbox.net/skill-version.json

이 setup-loftbox-domain 스킬은 스크립트를 직접 실행하여 호출합니다(설치 프로그램은 setup-loftbox-domain 셸 명령을 생성하지 않습니다). $SKILL_DIR 는 install.sh 이(가) 스킬을 배치한 위치입니다 — 예: ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, 또는 Hermes에서는 ~/.hermes/skills/email/setup-loftbox-domain. 이 스킬은 LoftBox API를 호출합니다 — API가 반환하는 DNS 값을 정확히 사용하고 절대 임의로 만들지 마세요:

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 는 register-loftbox-mail-agent (이메일 인증)와 setup-loftbox-domain (도메인 온보드 + DNS)를 처음부터 끝까지 오케스트레이션합니다. 6자리 이메일 토큰 단계는 사람이 필요하므로 완전히 무인으로 진행되지는 않습니다.

출시 시 개인 베타는 LoftBox 관리형 전송과 LoftBox 관리형 인바운드 MX 처리를 사용합니다. 커스텀 도메인은 검증 후에만 활성화됩니다.

에이전트와 메일박스

에이전트는 비즈니스 목적, 소유권 컨텍스트, 안정적인 외부 ID를 보유합니다. 메일박스는 해당 에이전트에 주소와 도메인을 연결합니다. 표시 이름, 소유자, 정책 범위를 운영자가 검토할 수 있을 만큼 명확하게 유지하세요.

• 운영 에이전트 또는 워크플로 역할마다 하나의 메일박스를 사용하세요.
• 중복 확인과 멱등적 에이전트 설정에는 external_id 을(를) 사용하세요.
• 프로덕션 아웃바운드 메일에는 검증된 커스텀 도메인을 사용하세요.
• 에이전트 목적이 불분명할 때는 자율 발송을 비활성화하거나 보류하세요.

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

LoftBox 관리형 개인 베타 도메인의 경우 domain_id 을(를) 생략하세요. 에이전트에 HTTPS endpoint가 있으면 에이전트 webhook을 별도로 등록하세요.

검증된 커스텀 도메인에서는 하나의 메일박스를 catch-all로 표시할 수 있습니다("is_catch_all": true 을(를) 생성 또는 업데이트 시 지정). 그러면 정확히 일치하는 메일박스가 없는 해당 도메인의 모든 주소가 그곳으로 라우팅됩니다 — 하나의 에이전트로 support@, sales@, 또는 anything@yourdomain을 수집하는 데 유용합니다.

메시지 발송

검증된 메일박스에서 API를 통해 운영 또는 트랜잭션 메시지를 발송합니다. LoftBox는 전송 참조, 전송 상태, rate-limit 결정, 운영자 승인 결과를 기록합니다.

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

전송을 예약하려면 send_at (RFC3339, 미래 시각)을 전달하고, 재시도를 중복 제거하려면 Idempotency-Key 헤더를 전달하세요(재전송 시 원본 메시지를 반환). 발송 또는 수신한 메시지를 GET /v1/messages?q=<text>&label=<name>(으)로 조회 및 검색하고, 스레드를 POST/DELETE /v1/messages/{id}/labels(으)로 정리하세요.

LoftBox는 대량 마케팅 발송기가 아닙니다. 구매한 리스트, 스크랩한 수신자, 일반 SMTP relay 사용은 MVP 정책을 벗어납니다.

인바운드 webhook과 폴링

회신은 인바운드 메시지로 저장됩니다. HTTPS endpoint가 있는 에이전트는 서명된 webhook 이벤트를 받을 수 있고, endpoint가 없는 에이전트는 메일박스 inbox를 폴링하여 처리한 각 메시지를 확인 처리해야 합니다.

• message.inbound새 인바운드 메시지 또는 회신이 파싱·스레드화되어 구성된 webhook으로 제공되었습니다.
• message.delivered수신자에 대한 전송이 보고되었습니다.
• message.failed아웃바운드 전송이 영구적으로 실패했거나 재시도 처리를 모두 소진했습니다.

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

webhook 시크릿은 webhook 생성 시 한 번 반환됩니다. 즉시 저장하고 이벤트 내용을 신뢰하기 전에 모든 인바운드 서명을 검증하세요.

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

에이전트가 메시지를 영속적으로 처리한 후에만 확인 처리하세요. inbox가 비어 있는 폴링은 백오프해야 하며, 활성 폴링은 30-60초 같은 적당한 간격을 사용해야 합니다.

실시간 스트리밍(WebSocket)

HTTPS webhook을 호스팅할 수 없는 에이전트(예: NAT 또는 firewall 뒤에서 실행)는 WebSocket을 통해 실시간으로 이벤트를 구독할 수 있습니다. 이 스트림은 webhook과 동일한 이벤트 유형을 1초 미만의 전송 속도로 전달하며, 연결이 끊긴 동안 놓친 이벤트를 cursor 기반으로 재생합니다. 이를 위해서는 receive scope가 필요합니다.

• GET /v1/wsWebSocket 업그레이드. Authorization: Bearer(으)로 인증합니다. 필터링은 ?event_types= 와 ?agent_id=(으)로 하고, 재개는 ?after=<cursor>(으)로 합니다.
• GET /v1/ws/asyncapi.json스트림에 대한 AsyncAPI 명세(공개).

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

코드가 error 또는 lagged 인 resync_required프레임에서는 마지막으로 받은 cursor를 사용하여 재연결하세요.

권한과 API 키

API 키는 scope를 가집니다. 광범위한 scope(send, receive, admin)는 세분화된 scope(message:send, message:read, domain:manage, approval:decide, keys:manage, …)를 함의하므로, 기존 키는 계속 작동하면서 하위 에이전트를 위한 최소 권한 자식 키를 발급할 수 있습니다.

• POST /v1/auth/keys자식 키를 발급합니다. 요청한 scope는 호출자의 scope의 부분집합이어야 합니다(권한 상승 불가). 선택적 expires_in_days. 평문 키는 한 번 반환됩니다.
• GET /v1/auth/keys조직 키를 나열합니다(메타데이터만, 시크릿 없음). 다음이 필요합니다: keys:manage.
• DELETE /v1/auth/keys/{id}키와 그 모든 하위 항목을 폐기합니다(cascade). 허용 대상: keys:manage 또는 해당 키의 부모.

DMARC 집계 리포트

메일박스 제공자(Gmail, Outlook, Yahoo, …)는 어떤 출발지 IP가 귀하의 검증된 도메인으로 메일을 보냈는지, SPF/DKIM/DMARC가 정렬되었는지 요약한 일일 DMARC 집계(rua) 리포트를 보냅니다. LoftBox는 이를 구조화된 리포트로 수집하여 전달성을 모니터링하고 스푸핑을 발견할 수 있도록 합니다. 저장된 각 리포트에는 인증된 리포터 도메인도 기록됩니다.

• GET /v1/dmarc/reports조직의 DMARC 집계 리포트를 최신순으로 나열합니다. cursor 페이지네이션은 before_date_end + before_id (다음으로 함께 반환됨: next_cursor)으로 합니다. 다음이 필요합니다: domain:read.
• GET /v1/dmarc/reports/{id}출발지 IP별 레코드(메시지 수, disposition, DKIM/SPF 정렬, header-from)와 함께 하나의 리포트를 조회합니다. 다음이 필요합니다: 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"

리포트는 제공자가 제출하는 대로 나타납니다(일반적으로 리포터당 하루 한 번). 귀하 자신의 검증된 도메인에 대한 리포트만 반환되며, 플랫폼 또는 호스팅되지 않은 도메인 리포트는 절대 노출되지 않습니다.

전송 이벤트

전송 상태는 관리형 전송 콜백과 내부 발송 상태 전반에 걸쳐 정규화됩니다. 지원 시에는 비공개 수신자 데이터가 아닌 이벤트 ID와 전송 참조를 사용하세요.

• queued: LoftBox가 전송을 위해 수락했습니다.
• sent: 아웃바운드 전송을 위해 수락되었습니다.
• delivered: 수신자에 대한 전송이 보고되었습니다.
• failed: 전송이 영구적으로 실패했거나 재시도를 모두 소진했습니다.
• blocked: 정책, rate limit, 또는 리포트 제어가 발송을 차단했습니다.

Rate limit과 리포트 제어

아웃바운드 발송은 조직, 에이전트, 메일박스, 수신자, 도메인 정책에 의해 제한됩니다. 개인 베타 조직은 하루 100건 발송으로 제한됩니다. 고위험 메시지는 전송 시도 전에 승인을 위해 보류될 수 있습니다.

다음 응답은 429 백오프로 처리하세요. 무한정 재시도하거나 다른 메일박스의 승인 보류를 우회하지 마세요.

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

관리형 전송과 안전 설정

LoftBox는 베타 계정에 대해 관리형 아웃바운드 전송을 운영합니다. 공개 문서는 내부 벤더 이름, 자격 증명, 라우팅 세부 정보를 노출하지 않고 고객에게 보이는 제어를 설명해야 합니다.

• 비즈니스 성격: 검증된 도메인 기반 AI 에이전트를 위한 API 관리형 운영 이메일 아이덴티티.
• 이메일 유형: 트랜잭션/시스템 알림, 검증된 사용자가 시작한 에이전트 회신, 온보딩/테스트 메시지, 리포트/연락 처리.
• 제어: 검증된 도메인만 허용, 명시적 rate limit, 전송 로그, 차단(suppression)/불만 처리, 모니터링되는 리포트 연락처.
• 공개 페이지: 개인정보 처리방침, 이용약관, 그리고 스팸 방지 정책.

DNS 전파와 전송 검증 보류는 API 프록시나 홈페이지 문서가 깨졌다는 증거가 아니라 설정 상태로 간주해야 합니다.