API와 MCP로 다른 주소에서 보내기

TrekMail은 서로 다른 자격 증명과 권한을 사용하는 두 가지 작업을 분리합니다.

1. 대시보드/Ops 인터페이스는 재사용 가능한 SMTP 프로필과 도메인 라우팅을 관리합니다. tm_live_ 토큰과 smtp:read 또는 smtp:write를 사용합니다.
2. 웹메일/메시지 인터페이스는 하나의 사서함과 하나의 연결된 받은편지함에서 사용할 수 있는 보내는 사람 주소를 관리합니다. tm_msg_ 토큰과 messages:read, messages:write 또는 messages:send를 사용합니다.

이는 의도적인 구분입니다. 사서함 토큰은 이미 승인된 전송 경로를 선택할 수 있지만 SMTP 자격 증명을 공개하거나 다른 계정의 인프라를 관리할 수는 없습니다.

요약

• external_account_id만 사용해 보내면 수신자에게 해당 연결 계정의 자체 주소가 표시되고 자체 SMTP 서버가 사용됩니다.
• 소스에 연결된 identity_id도 사용해 보내면 수신자에게 해당 ID의 비즈니스 주소가 표시됩니다. TrekMail은 ID에 할당된 도메인 경로 또는 저장된 SMTP 프로필을 사용한 다음 연결된 받은편지함의 보낸편지함에 사본을 저장합니다.
• Starter에서는 웹메일에서 이를 설정하고 사용할 수 있습니다. Pro와 Agency에서는 API 또는 MCP를 통한 자동화도 가능합니다. Nano에는 연결 계정 슬롯이 없습니다.

사용 가능한 API 및 MCP 도구는 제품과 함께 발전합니다. 다른 주소에서 보내기는 SMTP 및 메시지 도구 모음을 사용하며 각 연결에는 요금제, 범위, 승인된 권한이 허용하는 도구만 표시됩니다.

라우팅 모델

external_account_id를 identity_id 없이 보내면 TrekMail은 해당 외부 계정의 자체 SMTP 서버와 자체 주소를 사용해 전송합니다.

두 값을 모두 보내면 TrekMail은 외부 계정을 받은편지함/보낸편지함 대상으로, ID를 표시되는 보내는 사람 + SMTP 경로로 취급합니다.

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

ID와 외부 계정은 서로 연결되어 있어야 합니다. 소스를 생략하거나 다른 사서함의 ID를 제공하면 422 identity_unavailable가 반환됩니다.

1. 대시보드 API에서 SMTP 검사 또는 설정

Ops 토큰을 사용하세요.

프로필 조회는 비밀번호를 반환하지 않습니다. 사용 현황 endpoint를 통해 에이전트는 공유 프로필을 편집하거나 삭제하기 전에 그 영향을 안전하게 설명할 수 있습니다.

MCP 도구: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. 정확한 받은편지함의 주소 나열

메시지 토큰을 사용하세요.

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

응답에는 소스별 identities, 설정된 모든 external_identities, sending_addresses, 사용할 수 있는 send_as_domains, 사서함의 reply_from_policy, 그리고 계정 소유자 사서함에만 직접 선택할 수 있는 저장된 smtp_profiles가 포함됩니다.

MCP: list_identities를 external_account_id와 함께 호출하세요.

호스팅 MCP와 로컬 stdio

메시지 도구에는 중요한 전송 방식 차이가 하나 있습니다.

• 호스팅 HTTP MCP (OAuth): 모든 메시지 도구 호출에 mailbox_id도 전달하세요. 호스팅 서버는 이 값을 사용해 해당 사서함 전용의 수명이 짧은 메시지 토큰을 발급합니다. 예를 들어 list_identities를 { "mailbox_id": 7, "external_account_id": 42 }와 함께 호출하세요.
• 자체 호스팅 stdio MCP (tm_msg_): mailbox_id를 전달하지 마세요. 정적 메시지 토큰이 이미 하나의 사서함에 연결되어 있으므로 도구 스키마에는 external_account_id만 필요합니다.

external_account_id는 mailbox_id를 대체하지 않습니다. 이미 승인된 사서함 안에서 연결된 받은편지함을 선택합니다. 대시보드 SMTP 도구는 계속 계정 범위로 제한되며 두 전송 방식 모두에서 mailbox_id를 받지 않습니다.

3. 다른 주소에서 보내기 ID 만들기

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email은 이미 이 사서함의 기본 주소이거나 전송이 활성화된 유효한 별칭이어야 합니다. 해당 도메인은 활성 상태이고 같은 계정이 소유해야 합니다. smtp_mode: domain은 대시보드에 설정된 도메인 경로를 따릅니다. smtp_mode: profile은 ID를 smtp_connection_id에 고정하며 프로필 직접 선택은 계정 소유자 사서함으로 제한됩니다.

external_account_id는 선택 사항이며 그 의미를 정확히 이해해야 합니다.

• 연결된 Gmail, Outlook 또는 IMAP 받은편지함을 통해 해당 주소의 메일을 읽는 경우 포함하세요. 그러면 ID가 해당 받은편지함에 연결되며 그 받은편지함과만 사용할 수 있습니다.
• 메일을 TrekMail 사서함으로 전달하는 경우 생략하세요. 이는 고객이 자체 제공업체에 메일을 유지하고 사본을 팀 사서함으로 전달하는 공유 받은편지함 작업 흐름입니다. ID는 사서함 자체에 속하며 전송 권한이 있는 모든 구성원이 사용할 수 있습니다.

개인용 연결 받은편지함은 공유 사서함에 연결할 수 없습니다. 연결한 사람만 사용할 수 있는 비공개 항목입니다. 이 경우 external_account_id를 생략하세요.

MCP: create_identity를 kind=send_as로 호출하세요. 호스팅 MCP에서는 위에서 설명한 대로 상위 mailbox_id를 포함하세요.

4. 보내기, 초안 작성, 예약, 답장 또는 전달

일반 메시지 작업은 동일한 소스 쌍을 허용합니다.

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id는 즉시 보내기, 초안 저장/업데이트 및 예약 전송에서 지원됩니다. 답장/전달 준비는 external_account_id를 받고 배달 헤더에서 일치하는 ID를 선택합니다. 대기열의 메시지가 실제로 실행될 때 선택된 ID를 다시 승인합니다. 별칭, 도메인, 프로필 또는 연결 계정을 비활성화하면 다른 보내는 사람 주소로 조용히 대체되지 않고 배달이 중지됩니다.

MCP 도구: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all, prepare_forward.

답장 정책

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient는 가능하면 메시지를 받은 주소에서 답장합니다. 일반 사서함 메일에서 default는 항상 사서함 기본값으로 시작합니다. MCP는 set_reply_from_policy를 사용합니다.

안전 및 격리 규칙

• SMTP 자격 증명은 메시지 API 또는 MCP 응답에 포함되지 않습니다.
• 모든 외부 계정과 ID는 메시지 토큰의 사서함으로 제한됩니다.
• 연결된 다른 주소에서 보내기 ID는 정확한 external_account_id와만 사용할 수 있으며 사서함 소유 ID는 이 값 없이만 사용할 수 있습니다.
• 보내는 사람 주소는 이미 사서함 주소 또는 전송이 활성화된 별칭으로 승인되어 있어야 합니다. API는 임의의 보내는 사람 주소를 만들 수 없습니다.
• 만들기 전에 작동하는 경로가 필요하며 배달 시 다시 확인합니다.
• 사용자 지정 Reply-To 헤더는 ID에 저장된 Reply-To와 충돌할 수 없습니다.
• MCP에서 ID 및 프로필을 변경하려면 적절한 쓰기 권한이 필요합니다. 로컬에서 호스팅하는 MCP 관리자는 쓰기 작업에 명시적 승인을 요구할 수 있으며 전송에도 메시지별 확인이 필요합니다.

새 토큰 범위 문자열은 필요하지 않습니다. 기존 smtp:* 및 messages:* 토큰은 현재 권한에 따라 계속 작동합니다.

어떤 전송 한도가 적용되나요?

API 호출에도 자체 악용 방지 장치가 적용됩니다. 기본적으로 메시지 토큰당 분당 60개의 전송 요청과 사서함 전체에서 일일 100개의 API 전송이 허용됩니다. 최종적으로 어떤 서버가 이메일을 배달하든 적용됩니다.