Nylas Smart Compose를 사용하여 이메일 초안 생성하기

명확하고 구조가 잘 잡힌 이메일을 작성하는 데는 시간이 걸리며, 이는 LLM (Large Language Model)이 진정으로 잘 수행할 수 있는 종류의 작업입니다. 하지만 직접 프롬프트-이메일 파이프라인 (prompt-to-email pipeline)을 구축한다는 것은 모델을 선택하고, 원본 메시지를 컨텍스트 (context)로 스레딩(threading)하며, 스트리밍 (streaming)을 처리하고, 이 모든 것을 API 키 뒤에서 관리해야 함을 의미합니다. Nylas Smart Compose 엔드포인트 (endpoints)는 이 작업을 대신 해줍니다. 자연어 프롬프트 (natural-language prompt)를 보내면 작성된 메시지 본문을 돌려받으며, 답장 변형 (reply variant)은 원본 이메일을 컨텍스트로 자동 포함합니다.

이 포스트에서는 두 가지 관점에서 Smart Compose를 살펴봅니다: 백엔드를 위한 HTTP API와 터미널을 위한 nylas CLI입니다. 저는 CLI를 담당하고 있으므로, 아래의 터미널 명령어들은 제가 프롬프트를 테스트할 때 사용하는 것들입니다.

Smart Compose 작동 방식

Smart Compose는 프롬프트를 메시지 본문으로 변환하는 두 개의 엔드포인트로 구성됩니다. 자연어 prompt를 보내면, 생성된 텍스트를 담은 suggestion 필드가 포함된 응답이 돌아옵니다. 완전히 새로운 메시지를 작성하기 위한 POST /messages/smart-compose가 있고, 답장을 작성하기 위한 POST /messages/{message_id}/smart-compose가 있는데, 여기서 원본 메시지는 컨텍스트에 포함되어 응답이 실제로 그 질문에 답할 수 있게 합니다.

이해해야 할 핵심 사항은 Smart Compose는 텍스트를 생성할 뿐, 아무것도 전송하지 않는다는 것입니다. 반환된 suggestion은 사용자가 후속 조치를 취해야 하는 메시지 본문입니다. 이를 Send Message 엔드포인트로 바로 전달하거나, 사람이 먼저 검토하고 편집할 수 있도록 초안 (draft)에 미리 채워 넣을 수 있습니다. 이러한 분리는 의도적인 것으로, LLM이 작성한 내용에 대해 보통 원하는 방식인 'AI의 출력물과 수신자 사이에 사람을 두는 것'을 가능하게 하기 때문입니다.

시작하기 전에 알아두어야 할 두 가지가 있습니다. Smart Compose는 Agent Accounts가 아닌, 연결된 OAuth 권한 (OAuth grants)에 대해서만 실행됩니다. 또한 프롬프트에는 제한이 있습니다: 최대 1,000 토큰 (tokens)까지 가능하며, 더 긴 프롬프트는 에러를 반환합니다.

새 메시지 생성하기

새 이메일을 작성하려면, POST /v3/grants/{grant_id}/messages/smart-compose를 사용하며, 원하는 내용을 설명하는 단일 prompt (프롬프트)를 전달합니다. 응답의 suggestion (제안) 필드에 생성된 본문이 포함되며, 이를 전송하거나 저장할 수 있습니다. 프롬프트는 일반적인 자연어이므로, "우리 출시(launch)에 대한 비즈니스 브리프를 포함하여 Ron에게 보낼 이메일을 작성해줘"와 같은 입력이 유효합니다.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/smart-compose" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
...

터미널에서 nylas email smart-compose --prompt를 실행하면 초안을 생성하고 제안 내용을 출력합니다. 이는 프롬프트를 애플리케이션에 연결하기 전에 프롬프트가 무엇을 생성하는지 확인할 수 있는 가장 빠른 방법입니다:

nylas email smart-compose --prompt "Draft a thank you email for the meeting"

응답의 suggestion은 단순한 텍스트이므로, 자연스러운 다음 단계는 이를 전송(send) 또는 초안(draft)으로 넘기는 것입니다. Smart Compose를 Drafts API와 결합하면 '전송 전 검토(review-before-send)' 루프를 구현할 수 있습니다. 즉, 제안을 생성하고, 이를 바탕으로 초안을 만든 다음, 사람이 전송하기 전에 승인하도록 하는 방식입니다.

스레드 문맥(context)을 사용하여 답장 생성하기

답장은 Smart Compose의 진가가 발휘되는 부분입니다. 좋은 답장을 작성하려면 무엇에 대해 답하고 있는지 알아야 하기 때문입니다. POST /v3/grants/{grant_id}/messages/{message_id}/smart-compose는 동일한 prompt를 사용하지만, 답장하려는 메시지의 ID도 함께 받으며, 해당 원본 메시지를 문맥(context)으로 읽어들입니다. 사용자는 의도(intent)를 설명하기만 하면, 모델이 응답 대상인 이메일의 세부 사항을 처리합니다.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/<MESSAGE_ID>/smart-compose" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
...

CLI는 --message-id를 통해 메시지를 추가하며, 이를 전달하면 명령어가 새 메시지 작성에서 답장 작성으로 전환됩니다:

nylas email smart-compose \
  --message-id <message-id> \
  --prompt "Reply accepting the invitation"

엔드포인트(endpoint)가 원본 메시지를 읽기 때문에, 프롬프트(prompt)를 짧고 상위 수준(high-level)으로 유지할 수 있습니다. 답장하려는 이메일을 프롬프트에 직접 붙여넣을 필요 없이, ID로 참조하면 Smart Compose가 문맥(context)을 가져옵니다. 덕분에 원본 메시지가 길더라도 프롬프트를 1,000 토큰(token) 제한보다 훨씬 낮은 수준으로 유지할 수 있습니다.

답장 제안 루프(reply-suggestion loop) 구축하기

Smart Compose는 인바운드 흐름(inbound flow)에 자연스럽게 녹아듭니다. 메시지가 도착하면 message.created 웹훅(webhook)이 ID를 포함한 새 메시지를 전달하며, 이는 답장 엔드포인트에 정확히 필요한 정보입니다. 핸들러(handler)는 어떻게 응답할지를 설명하는 프롬프트와 함께 POST /messages/{message_id}/smart-compose를 호출하여 suggestion을 받고, 이를 바탕으로 검토를 위한 초안(draft)을 생성합니다.

고객 지원(support) 또는 영업(sales) 수신함의 경우, 이를 통해 모든 수신 이메일은 사람이 승인하기를 기다리는 미리 작성된 답장으로 변합니다. 코드가 메시지를 분류하고 상황에 맞는 프롬프트(예: "주문 번호를 요청하는 정중한 답장 작성")를 선택하면, 검토자는 빈 작성 창 대신 준비된 초안을 보게 됩니다. 메시지 ID는 이 루프를 하나로 묶어줍니다. ID는 응답할 이메일을 식별하고 Smart Compose에 문맥을 제공합니다. 결과물인 초안을 보낼 때는 동일한 ID를 reply_to_message_id로 전달하여, 수신자의 편지함에서 답장이 올바른 스레드(thread)로 묶이도록 합니다.

사용 가능한 이메일을 생성하는 프롬프트 작성하기

Smart Compose 프롬프트는 하나의 지시 사항이며, 프롬프트가 구체적일수록 제안된 결과물을 수정할 필요가 줄어듭니다. 이메일 수신자가 누구인지, 무엇을 달성해야 하는지, 그리고 원하는 어조(tone)를 명시하세요. 예를 들어, "환불이 처리되었으며 영업일 기준 5일 이내에 도착할 것임을 확인하는 고객 대상의 짧고 친근한 이메일을 작성해줘"라고 입력하는 것이 "환불 이메일 작성해줘"라고 하는 것보다 더 정교한 결과를 만들어냅니다. 모델은 구조와 문구를 채우고, 사용자의 프롬프트는 의도(intent)와 제약 조건(constraints)을 제공합니다.

답장을 작성할 때는 엔드포인트(endpoint)가 이미 가지고 있는 문맥(context)을 활용하세요. 모델이 원본 메시지를 읽기 때문에, 프롬프트에 원본 내용을 다시 기술할 필요 없이 그에 대한 답변을 설명하기만 하면 됩니다. 모델이 이미 회의 요청을 보고 있으므로, "회의를 거절하고 대신 목요일로 제안하는 답장을 써줘" 정도면 충분합니다. 프롬프트를 의도에 집중시키고 메시지 문맥이 세부 사항을 전달하게 하면, 1,000-토큰(token) 제한을 훨씬 여유롭게 유지할 수 있습니다.

응답을 스트리밍하거나 한 번에 받기

Smart Compose는 생성된 텍스트를 받는 두 가지 방법을 제공하며, 적절한 방법은 사용자의 인터페이스에 따라 달라집니다. 백엔드에서 소비하기 가장 간단한 방법으로, 전체 제안을 단일 JSON 응답으로 받으려면 Accept: application/json 헤더를 추가하거나 Accept 헤더를 완전히 생략하세요. 그러면 엔드포인트는 완성된 suggestion이 포함된 하나의 JSON 블록을 반환합니다.

사용자 대상의 경험을 위해서는 생성을 스트리밍(stream)할 수 있습니다. Smart Compose는 서버 전송 이벤트(Server-Sent Events, SSE)를 지원하므로, 채팅 인터페이스에서 글자가 타이핑되는 것과 동일한 효과처럼 모델이 생성하는 대로 토큰(token)을 하나씩 받을 수 있습니다. 스트리밍은 사용자가 전체 메시지를 기다리는 대신 텍스트가 즉시 나타나는 것을 볼 수 있기 때문에 체감 속도에서 눈에 띄는 차이를 만들어냅니다. 어떤 방식을 사용하든 콘텐츠는 동일하며, SSE는 단지 토큰이 도착하는 시점만 바꿀 뿐입니다.

전송 방식(transport)은 계정 설정이 아닌 요청별 선택 사항입니다. 따라서 하나의 통합 환경(integration) 내에서도 각 호출 시 헤더를 전환하는 것만으로, 대화형 작성 상자(interactive compose box)에는 스트리밍(streaming)을 적용하고 백그라운드 작업(background job)에서는 단일 블록(single-blob) 응답을 받도록 구성할 수 있습니다. 지연 시간(latency)은 프롬프트(prompt)의 길이와 복잡성에 따라 달라지므로, 어떤 전송 방식을 선택하든 짧은 대기 시간을 고려해야 합니다. UI에 "작업 중" 표시기를 제공하면 사용자가 요청이 중단되었는지 의구심을 갖는 것을 방지할 수 있으며, 이는 전체 메시지가 준비될 때까지 아무것도 나타나지 않는 단일 응답 방식에서 더욱 중요합니다.

제안을 전송된 메시지 또는 초안으로 전환하기

제안(suggestion) 그 자체는 단순한 문자열일 뿐이며, 진정한 가치는 그 다음에 무엇을 하느냐에서 나옵니다. 거의 모든 사례는 두 가지 패턴으로 커버됩니다. 검토가 필요 없는 자동 전송의 경우, suggestion을 가져와 Send Message 요청의 body에 넣고 전송하면 됩니다. 사람이 먼저 확인해야 하는 모든 경우에는 제안을 바탕으로 초안(draft)을 생성하여 사용자의 임시 보관함(Drafts folder)에 저장하고 편집할 수 있도록 합니다.

AI가 작성한 메일의 경우 초안 경로는 더 안전한 기본값입니다. 생성된 메시지는 이름을 잘못 부르거나, 부적절한 어조를 사용하거나, 세부 사항을 지어낼 수 있는데, 초안을 사용하면 수신자가 확인하기 전에 사람이 이를 바로잡을 기회를 가질 수 있습니다. 흐름은 다음과 같습니다: 제안을 생성하고, 이를 사용하여 초안을 만든 다음, 승인을 위해 해당 초안을 UI 또는 사용자의 메일 클라이언트에 노출합니다. 승인이 이루어진 후에만 메시지가 전송됩니다.

제안은 사용자가 제어할 수 있는 일반 텍스트(plain text)이므로, 어디로 보내기 전에 후처리(post-process)를 할 수도 있습니다. 인사말을 앞에 붙이거나, 사용자의 서명을 뒤에 추가하거나, 자체적인 검사 과정을 거칠 수 있습니다. 엔드포인트(endpoint)는 완성된 이메일이 아닌 본문(body)을 전달하므로, 마지막 단계(last mile)는 사용자의 몫으로 남습니다. Smart Compose가 직접 전송하는 대신 텍스트를 반환하는 이유도 바로 이러한 검토 루프(review loop) 때문입니다. 엔드포인트는 의도적으로 생성 단계에서 멈추어 전송 결정권을 사용자에게 남겨둠으로써, 사용 사례가 요구하는 만큼의 인간의 감독(human oversight)을 정확하게 삽입할 수 있도록 합니다.

요구 사항 및 제한 사항

몇 가지 제약 사항이 Smart Compose의 활용 범위를 결정합니다. 가장 큰 제약은 계정 모델(account model)입니다. 이 기능은 연결된 OAuth 권한(grants), 즉 사용자가 Google 또는 Microsoft를 통해 인증하는 메일함에서 작동하며, Agent Account에서는 사용할 수 없습니다. 만약 Agent Account를 기반으로 구축 중이며 AI가 작성한 메일을 원한다면, 자체 모델로 텍스트를 생성한 뒤 표준 Messages API를 통해 전송하십시오.

다른 요구 사항은 계정 설정에 관한 것입니다. Smart Compose는 인증 앱(auth app)과 커넥터(connector)를 통해 연결된 Google 또는 Microsoft 권한, 즉 표준 연결된 계정 흐름(connected-account flow)에서 작동합니다. 또한 각 호출 시 답장을 보내려는 메시지를 읽어야 하므로, gmail.readonly 또는 Mail.Read와 같은 읽기 권한(read scopes)이 필요합니다. 프롬프트(Prompts)는 1,000 토큰으로 제한되어 있습니다. 이는 지시 사항을 전달하기에는 넉넉한 양이지만, 긴 원본 이메일을 참조할 때는 내용을 직접 붙여넣기보다 메시지 ID(message ID)를 사용하여 참조해야 함을 의미합니다.

유의 사항

몇 가지 실무 지침을 따르면 Smart Compose를 단순한 데모용이 아닌, 프로덕션 환경에서 신뢰할 수 있는 기능으로 만들 수 있습니다.

사람이 읽는 모든 내용은 자동 전송하지 말고 초안(Draft)으로 만드세요. suggestion을 검토를 위한 초안으로 라우팅하십시오. AI 메일은 이름, 어조, 사실 관계를 틀리는 경우가 빈번하므로 인간의 확인(human check)이 필요합니다.
이메일을 붙여넣지 말고 message_id로 답장을 참조하세요. 답장 엔드포인트(reply endpoint)가 원본을 컨텍스트(context)로 읽어들이기 때문에, 프롬프트를 짧게 유지하고 1,000 토큰 제한을 준수할 수 있습니다.
사용자에게 보여주는 생성 작업에는 SSE(Server-Sent Events)를 사용하여 스트리밍하세요. 텍스트를 즉시 보여줄 수 있습니다. 단일 JSON 응답은 백엔드 자동화용으로 남겨두십시오.
생성할 뿐, 전송하지 않습니다. 엔드포인트는 본문(body)을 반환할 뿐이며, 이를 전송할지 아니면 초안으로 저장할지는 사용자가 결정합니다.
연결된 권한(connected-grant)에서만 작동합니다. Smart Compose는 Agent Account에서 사용할 수 없으므로, 해당 계정에서의 AI 메일은 자체 모델과 Messages API를 조합하여 계획하십시오.
프롬프트를 구체적으로 작성하세요. 수신자, 목표, 어조를 명시하십시오. 모호한 지시보다 정확한 지시가 편집 과정을 훨씬 줄여줍니다.

마치며

Smart Compose는 "AI로 이메일 작성하기"라는 과정을 단 하나의 요청으로 압축합니다. 즉, 프롬프트 (prompt)를 보내고, suggestion을 받아, 이를 바로 전송하거나 초안 (draft)으로 저장하는 것입니다. 응답 엔드포인트 (reply endpoint)는 원본 메시지를 컨텍스트 (context)로 추가하여 사용자의 프롬프트가 짧은 지시문으로 유지될 수 있게 하며, SSE 스트리밍 (SSE streaming)은 사용자가 AI에게 기대하는 타이핑 효과를 사용자 인터페이스 (user-facing interface)에 제공합니다. 이때 반드시 유지해야 할 하나의 습관은 생성된 메일을 검토를 위해 초안 (draft)으로 라우팅 (routing)하는 것입니다. 엔드포인트가 텍스트를 정확하게 전달해주므로, 수신자에게 도달하기 전에 어떤 일이 일어날지 직접 결정할 수 있기 때문입니다.

다음 단계:

Using Smart Compose — 스트리밍 (streaming)을 포함한 전체 가이드
Generate a new message 및 respond to a message — 엔드포인트 (endpoint) 참조
Send email 및 manage drafts — 제안 (suggestion) 이후의 단계
Nylas CLI email send — 제안이 완성된 메시지 전송