Agent Account 시작 가이드

Nylas Agent Account란?

AI 에이전트에는 이메일 송수신 기능이 필요합니다. 셀프호스팅 이메일은 5개 시스템을 직접 관리해야 합니다: DNS MX 레코드(전파에 24-48시간), Postfix나 Exim 같은 SMTP 데몬 (2020년 이후 12건의 보안 권고, 공식 공지 목록 참조), SpamAssassin을 통한 스팸 필터링, 분기마다 갱신하는 TLS 인증서, 그리고 RFC 5322 와이어 포맷용 MIME 파서.

Nylas Agent Account는 이 5개 모두를 하나의 CLI 명령으로 대체합니다. OAuth 자격 증명, MX 레코드, 서드파티 메일함 없이 이메일을 보내고 받을 수 있는 완전 관리형 이메일 ID를 제공합니다. API가 2초 이내에 주소를 프로비저닝하고 Grant를 반환합니다. 이 Grant는 Gmail, Outlook, IMAP 연결에 사용되는 것과 동일한 엔티티 타입이므로 모든 표준 이메일, 캘린더, 연락처 엔드포인트가 동일하게 작동합니다. 주소는 *.nylas.email 도메인에 위치하며, OAuth로 연결된 메일함과 동일한 Nylas v3 API 에 연결됩니다.

Agent Account로 무엇을 할 수 있나요?

Agent Account는 하나의 ID로 에이전트에 3가지 기능을 제공합니다: 이메일, 캘린더, 연락처. Grant 하나, API 키 하나, Workspace 하나. 에이전트가 받은편지함을 읽고, 여유 시간을 확인하고, 캘린더 이벤트를 만들 수 있습니다. 별도의 서비스나 연동이 필요 없습니다. Agentmail, Cloudflare Email Workers, Postmark 등도 관리형 이메일 계정을 제공하지만, 동일한 ID에서 캘린더나 연락처 엔드포인트를 포함하는 곳은 없습니다.

모든 기능은 OAuth 연결 메일함에서 이미 사용하는 것과 동일한 CLI 및 API로 작동합니다. 에이전트가 nylas email send로 이메일을 보낸다면, nylas calendar events list와 nylas contacts list도 실행할 수 있습니다. 추가 설정이나 자격 증명이 필요 없습니다. MCP를 통해 연결하는 AI 에이전트는 동일한 서버 연결에서 36개 도구 모두를 사용할 수 있습니다.

Agent Account는 어떻게 만드나요?

Agent Account 생성은 하나의 CLI 명령으로 2초 이내에 완료됩니다. 명령은 provider=nylas로 Grant를 프로비저닝하고, 관리형 Connector가 없으면 자동 생성하며, Grant를 로컬에 저장하여 이후 명령이 자동으로 해석합니다. OAuth 핸드셰이크, DNS 전파, 대시보드 클릭이 필요 없습니다.

nylas agent account create 명령은 원하는 이메일 주소를 유일한 인자로 받습니다. 도메인은 애플리케이션의 *.nylas.email 영역입니다. 주소는 명령 반환 후 2초 이내에 활성화되어 발송 가능합니다:

nylas agent account create support@yourapp.nylas.email

✓ Agent account created successfully!

Email:      support@yourapp.nylas.email
Provider:   nylas
Status:     valid

계정이 생성되면, 다른 Grant와 동일한 nylas email send 명령으로 이메일을 보냅니다. 발신자 주소는 활성 Grant에서 자동으로 가져오므로 --from 플래그가 필요 없습니다. *.nylas.email 도메인에서 DKIM 서명된 배달이 2초 이내에 완료됩니다:

nylas email send \
  --to customer@example.com \
  --subject "Your receipt" \
  --body "Order #4821 confirmed. Shipping Tuesday."

에이전트의 받은편지함 읽기는 nylas email list를 사용합니다. --json을 추가하면 에이전트 루프나 셸 파이프라인에서 파싱할 수 있는 구조화된 출력을 얻습니다. Nylas v3 API는 호출당 최대 200개의 메시지를 반환합니다:

nylas email list --limit 5 --json | jq '.[] | {from: .from[0].email, subject}'

이것으로 작동하는 에이전트 ID가 완성됩니다. 생성, 발송, 수신 3개 명령으로 완료. 앱 비밀번호를 통한 IMAP/SMTP 접근, 상태 확인, 프로덕션 제한 사항을 포함한 전체 워크스루는 AI 에이전트 이메일 ID 생성을 참조하세요.

Agent Account의 아키텍처는?

Agent Account는 5개의 엔티티 체인으로 구성됩니다: Application, Connector, Grant, Workspace, 그리고 Policy와 Rules. Application은 API 키를 보유하고, Connector는 관리형 프로바이더 타입을 정의하며, Grant는 이메일 ID 자체이고, Workspace는 정책과 규칙 설정을 그룹화하며, Rules는 인바운드 및 아웃바운드 이메일을 필터링하는 조건-액션 쌍을 정의합니다. 하나의 애플리케이션에서 이 체인을 통해 수백 개의 Agent Account를 관리할 수 있습니다.

각 엔티티의 역할은 다음과 같습니다:

• Application — 프로젝트 수준의 컨테이너. API 키, 리전 설정 (US 또는 EU), 모든 커넥터를 보유합니다. Nylas Dashboard에서 한 번 생성합니다.
• Connector — 프로바이더 타입을 정의합니다. Agent Account의 경우 Nylas 관리형 프로바이더입니다. 첫 번째 nylas agent account create 호출 시 CLI가 자동 생성하므로 수동 커넥터 설정이 필요 없습니다.
• Grant (Agent Account) — 개별 이메일 ID. 이메일 주소, 상태 필드, 설정에 연결되는 workspace_id를 가집니다. 모든 표준 이메일, 캘린더, 연락처 엔드포인트에서 작동하며, 받은편지함 읽기를 처리하는 동일한 Grant가 nylas calendar events list와 가용성 조회에도 사용됩니다.
• Workspace — 정책과 규칙 설정의 연결 지점. policy_id와 rules_ids[] 참조를 보유합니다. 이 엔티티는 ID와 동작 제약 사이의 아키텍처 레이어입니다.
• Policy — Workspace의 아웃바운드 제약을 정의합니다(속도 제한, 도메인 제한).
• Rules — 조건-액션 쌍. 각 규칙은 발신자 도메인이나 수신자 같은 엔벨로프 필드에서 매칭한 후 액션을 실행합니다: block, archive, mark_as_read, mark_as_starred.

Workspace란? 왜 존재하나요?

Workspace는 Agent Account의 Grant와 정책/규칙 사이에 위치합니다. policy_id를 Grant 설정에 직접 저장하는 대신, Workspace가 policy_id와 rules_ids[]를 별도 참조로 보유합니다. 이것이 중요한 이유는 Grant를 건드리지 않고 정책을 교체할 수 있고, 정책과 독립적으로 규칙을 관리할 수 있으며, 계정 간에 설정을 공유할 수 있기 때문입니다.

Workspace는 Nylas API의 /v3/workspaces/{id}에 위치합니다. Agent Account를 생성하면 API가 Grant와 Workspace를 한 번의 호출로 프로비저닝합니다(2초 이내). Workspace를 직접 다룰 일은 없습니다. nylas agent policy list를 실행하면 CLI가 기본 Grant를 로드하고, Workspace를 가져오고, Workspace의 policy_id를 읽어 연관된 정책을 반환합니다. 이 체인은 사용자에게 보이지 않습니다.

이 간접 참조에서 3가지 아키텍처 이점이 생깁니다:

1. 정책 교체 — Grant가 아닌 Workspace를 패치하여 정책을 전환합니다. ID는 안정적으로 유지되면서 동작이 변경됩니다. 다운타임 없이 업데이트당 200 ms 미만.
2. 독립적인 규칙 관리 — 정책 객체를 건드리지 않고 Workspace에서 규칙을 추가하거나 제거할 수 있습니다. Workspace의 rules_ids[] 배열이 해당 계정의 공식 규칙 목록입니다.
3. 멀티테넌시 — 동작 제약을 공유하는 계정은 같은 Workspace를 가리킬 수 있고, 각 계정이 개별 Workspace를 가질 수도 있습니다. 50개의 Agent Account가 있는 하나의 애플리케이션이 3개의 Workspace를 사용할 수 있습니다: 지원 받은편지함용, 알림 발신자용, 테스트 자동화용.

이것이 빛나는 순간: 에이전트가 시간당 500통 상한의 정책으로 고객 영수증을 발송하고 있습니다. 마케팅팀이 캠페인을 위해 상한을 올리고 싶어합니다. Workspace가 없다면 Grant 설정에 패치를 적용해야 하고, 발송 중인 에이전트가 중단될 위험이 있습니다. Workspace가 있으면 한 번의 PATCH 호출로 Workspace의 정책을 교체하면 됩니다. Grant는 변하지 않습니다. 에이전트는 재시작하지 않습니다. 200 ms 미만, 다운타임 제로.

nylas agent account get을 실행하면 Agent Account의 Workspace 연결을 확인할 수 있습니다. Workspace ID 필드가 ID와 설정을 연결합니다:

nylas agent account get me@yourapp.nylas.email

Email:        me@yourapp.nylas.email
Provider:     nylas
Status:       valid
Workspace ID: ws_abc123

인바운드 이메일은 어떻게 Agent Account에 도달하나요?

누군가 에이전트의 *.nylas.email 주소로 이메일을 보냅니다. 메시지가 Nylas의 관리형 메일 인프라에 들어가고, 이메일 주소로 Grant를 해석하고, Workspace를 로드하여 우선순위 순서로 규칙을 평가합니다. 차단 규칙이 없으면 메시지가 받은편지함에 도착합니다. 외부 발신자에서 배달 완료까지 95%의 메시지가 3초 이내에 처리됩니다.

인바운드 경로는 4단계로 구성됩니다:

1. MX 해석 — Nylas가 *.nylas.email의 MX 레코드를 관리합니다. 발신 서버는 사용자 인프라가 아닌 Nylas의 메일 인프라에 연결합니다. DNS 설정이 필요 없습니다.
2. Grant 조회 — 메시지의 수신자 주소가 해당 Grant에 매칭됩니다. 각 에이전트 주소는 정확히 하나의 Grant에 매핑됩니다.
3. Policy / Rules 평가 — Grant의 Workspace가 로드되고, 정책과 rules_ids[]의 각 규칙이 우선순위로 평가됩니다. 규칙은 엔벨로프 필드(발신자 도메인, 발신자 주소, 제목)에서 매칭합니다.
4. 배달 또는 차단 — 규칙이 block을 실행하면 메시지가 거부됩니다. 그렇지 않으면 받은편지함에 도착하고, 등록된 message.created 웹훅이 트리거됩니다.

아웃바운드 이메일은 어떻게 Agent Account에서 나가나요?

에이전트가 nylas email send를 호출하거나 v3 Messages API에 요청합니다. 요청이 활성 Grant를 해석하고, Workspace를 로드하고, 아웃바운드 정책을 평가한 후 Nylas의 트랜잭션 발송 파이프라인을 통해 메시지를 라우팅합니다. Grant 해석에서 수신자의 메일 서버까지 2초입니다.

아웃바운드 경로는 4단계로 구성됩니다:

1. Grant 해석 — CLI가 활성 Agent Account Grant를 해석합니다. 발신자 주소는 Grant에서 자동으로 가져오므로 --from 플래그가 필요 없습니다.
2. Workspace 조회 — Grant의 workspace_id가 조회됩니다. Workspace는 아웃바운드 동작을 제어하는 정책과 규칙을 보유합니다.
3. Policy / Rules 평가 — 아웃바운드 제약과 규칙이 확인됩니다. 정책이 수신자 도메인을 제한하거나, 규칙이 발송을 차단하거나, 발송 속도가 제한을 초과하면 SMTP에 도달하기 전에 요청이 거부됩니다.
4. 트랜잭션 발송 — Nylas가 *.nylas.email 도메인의 DKIM으로 메시지에 서명하고 수신자의 메일 서버로 배달합니다. 배달 시 message.send_success 웹훅이 발동합니다.

Agent Account가 셀프호스팅 이메일을 대체하는 이유

셀프호스팅 이메일은 5개의 별도 시스템이 필요하며, 각각 유지보수와 보안 오버헤드가 따릅니다. Postfix 공식 공지 목록에 따르면 가장 인기 있는 오픈소스 MTA가 2020년 이후 12건의 보안 권고를 발표했습니다. 권고마다 패치, 재시작, 확인 테스트가 필요합니다. Agent Account는 이 5개 시스템 모두를 2초 이내에 메일함을 프로비저닝하는 한 번의 API 호출로 대체합니다.

아키텍처적 차이점은 Agent Account가 메일 인프라를 API 경계 뒤로 밀어넣는다는 것입니다. 데몬, 인증서, DNS 레코드를 관리할 필요가 없습니다. 엔드포인트를 호출하면 됩니다. 정책과 규칙 적용은 메시지가 SMTP에 도달하기 전 Workspace 레이어에서 이루어지므로, AI 에이전트를 대상으로 한 프롬프트 인젝션이 제약을 우회할 수 없습니다. 격리 패턴에 대한 자세한 내용은 AI 에이전트의 폭주 방지를 참조하세요.

Agent Account는 커스텀 도메인도 지원합니다. *.nylas.email 대신 자체 도메인에서 송수신할 수 있습니다. 빠른 프로토타이핑과 테스트 자동화에는 관리형 도메인이 바로 사용 가능합니다. 프로덕션 브랜딩이 필요할 때는 Nylas Dashboard에서 커스텀 도메인을 설정하세요.

다음 단계

• AI 에이전트 이메일 ID 생성 — 실습 가이드: 계정 생성, 앱 비밀번호 추가, 2분 만에 송수신
• Agent Rules and Policies 완전 가이드 — 모든 트리거, 조건, 연산자, 액션, 정책 설정과 실제 예시
• AI 에이전트의 폭주 방지 — 에이전트가 발송하기 전에 격리 정책과 규칙을 Workspace에 연결
• AI 코딩 에이전트에 이메일 주소 부여 — Claude Code, Cursor, Codex를 MCP로 에이전트 ID에 연결
• SMTP 서버 없이 이메일 수신 — 웹훅, 실시간 처리, 테스트별 격리 받은편지함
• 에이전트 간 이메일 통신 — 2개의 Agent Account를 만들고 구조화된 JSON을 교환
• AI 에이전트를 위한 최적의 이메일 인프라 — Agent Account, 프로바이더 API, IMAP, SMTP, MCP, CLI 도구 비교
• 명령 참조 — 모든 nylas agent 플래그와 하위 명령
• Nylas v3 API 문서 — Agent Account Grant가 연결되는 API