개발자를 위한 TrekMail REST API 개요

TrekMail API를 사용하면 HTTP 클라이언트 또는 AI 에이전트에서 도메인, 사서함, 전달, DNS, 이메일 마이그레이션 및 웹메일 작업을 관리할 수 있습니다. 여기에는 메일 읽기와 전송, 임시 보관, 예약, 폴더, 연락처, 캘린더, ID, 템플릿 및 차단된 발신자가 포함됩니다. 인증된 요청은 bearer 토큰을 사용하고 응답은 JSON이며 API 활동은 감사됩니다.

제공되는 기능

• JSON 요청/응답 형식을 사용하는 REST API v1.
• Bearer 토큰 인증: 인증된 API 호출에는 쿠키나 세션을 사용하지 않습니다.
• 필요한 쓰기 작업에 멱등성 키를 적용하여 재시도 중 중복 작업을 방지합니다.
• Retry-After 헤더를 사용하는 토큰별 속도 제한.
• 대시보드의 AI 에이전트 및 API → 감사 로그에서 확인할 수 있는 감사 로그.
• 현재 연결의 자격 증명, 전송 및 안전 설정에 맞게 필터링된 카탈로그를 제공하는 MCP 서버. 따라서 범위가 좁은 프로젝트 연결에는 사용할 수 있는 도구만 표시됩니다.
• 도메인 별칭: 보조 도메인의 수신 전용 주소를 기본 도메인의 동일한 로컬 부분에 연결하며 저장 상태와 실제 배달 상태 및 안전한 제거를 지원합니다. API 및 MCP를 통한 도메인 별칭을 참조하세요.
• 이중 토큰 아키텍처: 인프라용 운영 토큰과 읽기, 전송, 임시 보관, 예약, 연락처, 캘린더, ID, 템플릿 및 폴더 같은 전체 이메일 작업용 메시지 토큰을 분리합니다.
• 발신 메일 배달 가능성과 반송 정보: 대시보드에서 전송, 배달, 하드 바운스 및 소프트 바운스 집계와 수신자별 SMTP 코드 및 응답을 가져옵니다. 배달 가능성과 반송을 참조하세요.
• 사서함 저장 공간 사용량: list_mailboxes와 get_mailbox는 used_mb, quota_mb, allocation_mb 및 is_pooled를 반환하므로 에이전트는 대시보드 없이도 한도에 가까운 사서함을 확인할 수 있습니다.
• White Label 관리: 설정 검토, 도메인별 브랜딩 관리, 클라이언트 초대, 역할 및 도메인 제어, 액세스 정지 또는 복원, API나 MCP를 통한 활동 검토가 가능합니다. 브랜딩 가이드와 팀 관리 가이드를 참조하세요.

Drive API 및 파일 자동화

Drive는 공개 API 영역에 포함됩니다. 계정 Drive와 사서함 Drive 공간, 사용량, 폴더 탐색, 업로드, 파일 및 폴더 관리, 휴지통, 대량 작업, 공개 공유 링크, 동기화 기기 비밀번호 관리 및 읽기 전용 Drive Storage Add-on 상태를 다룹니다.

Drive는 다음과 같은 열한 개의 운영 토큰 범위를 사용합니다. drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read, drive:devices:write. Drive Add-on의 결제 작업인 구매, 크기 변경 및 취소는 대시보드에서만 가능하며 API 또는 MCP 쓰기 작업으로 제공되지 않습니다.

Drive API 개요 또는 Drive API 빠른 시작부터 시작하세요.

이중 토큰 아키텍처

API는 서로 독립적인 두 가지 토큰 유형을 사용합니다. 필요에 따라 하나 또는 둘 다 사용할 수 있습니다.

운영 토큰과 메시지 토큰은 별도의 범위와 별도의 속도 제한을 사용합니다. 한 에이전트가 MCP 서버 환경에서 두 토큰을 구성하여 동시에 사용할 수 있습니다.

메시지 토큰은 Pro 및 Agency 요금제에서 사용할 수 있습니다.

시작하기 전에

• 모든 요금제에서 API 액세스를 제공합니다.
  • Nano: Email Verifier. 전체 Drive API 및 MCP 액세스에는 Drive Storage Add-on을 추가하세요.
  • Starter: 전체 Drive, 전체 Email Verifier 및 나머지 인프라 영역에 대한 읽기 전용 액세스를 제공합니다. 해당 쓰기 작업에는 대시보드를 사용하세요.
  • Pro / Agency: 메시지 토큰을 포함한 전체 기본 API 액세스를 제공합니다. 평가판 또는 유료 White Label 애드온이 활성화된 동안 White Label 범위가 추가됩니다.
• AI 에이전트를 연결하나요? 호환되는 클라이언트에 원격 MCP 서버로 https://trekmail.net/mcp를 추가하세요. 브라우저 승인을 지원하면 수동 토큰이 필요하지 않습니다. 원격, CLI/데스크톱, 브리지 및 자체 호스팅 옵션은 AI 에이전트 연결하기 (MCP)를 참조하세요.
• 직접 통합을 개발하나요? AI 에이전트 및 API → 토큰 → 토큰 생성에서 tm_live_ 토큰을 만들고 Authorization: Bearer …로 전송하세요. API 토큰 생성 및 관리를 참조하세요.
• API가 처음인가요? AI 에이전트 및 API 페이지 상단의 둘러보기 시작을 클릭하여 연결 방법, 토큰 관리, 연결된 앱 및 감사 로그에 대한 간단한 안내를 확인하세요.

인증 작동 방식

모든 요청은 Authorization 헤더에 토큰을 포함해야 합니다.

Authorization: Bearer tm_live_abc123...

운영 토큰은 tm_live_로 시작하고 메시지 토큰은 tm_msg_로 시작합니다. 둘 다 생성 시 한 번만 표시되며 다시 표시할 수 없습니다.

토큰이 없거나 취소되었거나 만료된 경우 API는 401을 반환하며 오류 코드는 unauthenticated입니다.

기본 URL 및 버전 관리

모든 엔드포인트는 다음 경로 아래에 있습니다.

https://trekmail.net/api/v1

기본 URL은 AI 에이전트 및 API 대시보드의 빠른 참조에 표시됩니다. 버전은 URL 경로에 포함됩니다. 향후 v2가 도입되더라도 v1은 계속 작동합니다.

응답 형식

성공한 응답은 단일 리소스의 data 키 또는 페이지가 매겨진 목록을 포함하는 JSON을 반환합니다.

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

오류 응답은 일관된 구조를 따릅니다.

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

요청 ID

모든 응답에는 X-Request-Id 헤더가 포함됩니다. 요청에서 X-Request-Id를 직접 전달할 수도 있습니다. 이 값은 그대로 반환되고 감사 기록에 저장됩니다.

속도 제한

각 토큰에는 분당 속도 제한이 적용됩니다. 제한에 도달하면 API가 429를 반환하며 Retry-After 헤더로 재시도 시점을 알려줍니다.

파괴적 작업(삭제 의도)에는 토큰별 일일 제한과 연속 삭제 사이의 대기 시간도 적용됩니다.

마이그레이션 쓰기 작업(시작, 취소, 재시도)에는 토큰당 분당 10개 요청의 전용 속도 제한이 있으며, 전역에서 너무 많은 마이그레이션이 실행 중이면 503을 반환하는 서버 전체 동시 실행 한도도 있습니다.

메시지 토큰은 별도의 제한을 사용합니다. 기본값은 토큰당 분당 읽기 요청 30개, 토큰당 분당 전송 요청 60개, 토큰당 하루 성공한 읽기 5,000개, 사서함 하나에서 하루 API 전송 100개입니다. 두 번째 전송 안전 카운터의 기본값은 토큰당 하루 500개이며, 일반적으로 더 낮은 사서함 한도가 먼저 적용됩니다. 이러한 API 안전장치는 요금제의 관리형 SMTP 제한이나 외부 제공업체 자체 제한을 대체하지 않습니다.

멱등성

멱등으로 표시된 상태 변경 엔드포인트에는 Idempotency-Key 헤더가 필요합니다. 자동 재시도로 작업이 중복될 수 있는 생성, 업데이트, 전송 및 삭제가 여기에 포함됩니다. 제공업체 감지나 연결 테스트 같은 읽기 성격의 POST 작업에는 필요하지 않습니다. 엔드포인트 표 또는 OpenAPI 명세를 확인하세요. 동일한 본문과 동일한 키를 보내면 API는 중복을 만들지 않고 원래 응답을 재생합니다.

Idempotency-Key: create-mailbox-alice-2024

동일한 키에 다른 본문을 보내면 API가 409 Conflict를 반환합니다.

사서함 저장 공간 할당

사서함 또는 초대를 생성하는 모든 엔드포인트 POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk는 선택적 정수 storage_allocation_mb를 받습니다.

할당량은 현재 풀에서 기존 전용 사서함과 대기 중인 전용 초대를 뺀 용량을 기준으로 검증됩니다. 대량 엔드포인트는 배치 전체 할당량의 합계도 검증하며 초과 할당이 발생하면 전체 배치를 422 storage_pool_exceeded로 거부합니다. 전용 사서함이 삭제되거나 초대를 사용하여 할당량이 새 사서함으로 이동하거나 대기 중인 초대가 만료되면 풀이 갱신됩니다.

초대의 경우 할당량은 액세스 코드에 기록되고 초대를 사용할 때 새 사서함으로 복사됩니다. 사용 시점에 요청된 할당량이 더 이상 풀에 맞지 않으면(예: 그사이 다른 관리자가 전용 할당량을 늘린 경우) 사용이 실패하지 않고 새 사서함을 공유 방식으로 안전하게 낮추며, 수신자는 성공 페이지에서 알림을 확인합니다.

사서함 Drive 액세스

모든 사서함에는 사용자가 웹메일에서 이용할 수 있는 Drive 범위를 결정하는 drive_access 수준이 있습니다. 이 값은 사서함 리소스에 반환되며 PATCH /api/v1/mailboxes/{id}로 설정하거나 여러 사서함에 대해 POST /api/v1/mailboxes:drive-access로 설정할 수 있습니다.

저장 공간은 계정 전체에서 공유되므로, 이 설정으로 한 사용자가 파일을 통해 풀을 얼마나 채울 수 있는지 제어합니다.

사서함 로그인 정지

메일은 계속 수신하면서 사서함 로그인을 정지할 수 있습니다. 웹메일, IMAP, SMTP 및 기기 비밀번호가 거부되고 열린 세션은 종료되지만 배달에는 영향이 없으므로 반송되지 않으며 로그인 복원 시 모든 메일이 대기 중입니다. POST /api/v1/mailboxes/{id}:suspend-login 및 :resume-login으로 설정하거나 여러 사서함에는 POST /api/v1/mailboxes:login-access를 사용하세요.

사서함 리소스는 이를 login_suspended, login_suspended_at 및 login_suspended_reason으로 보고합니다. 사용자가 로그인할 수 있는지는 login_suspended를 읽고, 사서함 자체의 실행 여부는 status를 읽으세요. 정지된 사서함은 메일을 계속 받으므로 active 상태를 유지합니다. :pause는 다른 기능으로, status를 disabled로 설정하고 배달도 중단합니다.

API를 통한 사서함 로그인 정지를 참조하세요.

대량 엔드포인트는 mailbox_ids, domain_id 또는 all 중 정확히 하나의 선택자를 받고 수행한 작업을 반환합니다.

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

도메인 하나가 고객 한 명에 해당한다면 domain_id 선택자를 사용하세요. 이미 요청 수준에 있는 사서함은 matched에는 포함되지만 updated에는 포함되지 않으므로 안전하게 호출을 반복할 수 있습니다.

공유 사서함은 단일 엔드포인트에서 422 drive_access_not_applicable로 거부되고 대량 엔드포인트에서는 건너뛰며 개수에 포함됩니다. 자체 웹메일 사용자가 없고 구성원이 자신의 수준으로 열기 때문에 공유 행에 저장된 값은 아무것도 변경하지 않습니다.

이 제한은 인터페이스뿐 아니라 API에도 적용됩니다. 제한된 사서함의 Drive 공간은 GET /api/v1/drive/spaces에 나타나지 않고, 해당 파일은 id로 요청하면 404를 응답하며 동기화 기기도 생성할 수 없습니다.

전달 주소

GET /api/v1/domains/{id}/forwarding-addresses는 전달 주소 자체에 드러나지 않는 두 가지 정보가 있으므로 목록 외의 정보도 반환합니다.

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max는 도메인별로 적용되며 요금제에 따라 Pro는 100, Agency는 300, Nano 또는 Starter는 저장되지만 비활성인 25개입니다.
• delivery.active는 이 규칙이 현재 메일을 이동하고 있는지를 나타냅니다. 요금제가 false 상태가 되는 기준인 requires_plan보다 낮을 때와, 계정이 시간당 전송 속도를 초과하여 false가 되는 paused_until 설정 기간에 배달이 중단됩니다(요금제별 전송 한도 참조). 규칙이 is_active: true여도 배달하지 않을 수 있으므로 전달이 작동한다고 보고하기 전에 delivery를 확인하고 is_active만 보지 마세요.

배달할 수 없는 요금제에서도 생성을 허용하며 201을 반환합니다. 규칙은 저장되고 업그레이드 후 작동을 시작합니다. 이는 해당 규칙을 저장됨 및 비활성으로 표시하는 대시보드와 동일합니다.

거부는 422로 반환되며 error.code는 validation_error 또는 limit_exceeded로 설정됩니다. 원인은 도메인에서 이미 사용 중인 주소, 루프를 일으킬 동일 도메인의 수신자, 정상 작동하는 MX가 없는 수신자 도메인 또는 가득 찬 도메인별 한도일 수 있습니다.

이 엔드포인트의 POST와 DELETE에는 Idempotency-Key가 필요하지만 PATCH에는 필요하지 않습니다.

배달 기록

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log는 최근 메일에 실제로 발생한 일을 최신순으로 반환합니다.

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome은 delivered, deferred(일시적 실패, 계속 재시도), failed(수신자의 서버가 거부) 및 blocked 중 하나입니다. 마지막 값은 전달 전에 스팸 필터가 메시지를 차단하여 수신자에게 전혀 도달하지 않았음을 뜻합니다. blocked를 반송으로 처리하면 실제로는 당사에서 발생한 문제를 두고 수신 서버를 조사하게 됩니다.

limit(1-200, 기본값 100)이 유일한 매개변수입니다. 기간은 요금제의 보존 기간으로 Agency는 30일, 나머지는 7일이며, 전달 이벤트는 정리되므로 더 오래된 항목은 조회할 수 없습니다.

공유(팀) 사서함

공유 사서함은 support@ 또는 sales@ 같은 팀 받은 편지함으로, 구성원이 자신의 일반 사서함 계정을 통해 Webmail에서 열며 기본 액세스가 활성화된 경우 위임된 IMAP 폴더로도 엽니다. 공유 비밀번호나 별도 로그인이 없습니다. 액세스는 균일합니다. 모든 구성원이 읽을 수 있고 단일 can_send 플래그가 해당 구성원이 주소로 회신할 수 있는지(true) 또는 읽기 전용인지(false)를 제어합니다. 구성원 역할은 없습니다.

GET /api/v1/mailboxes 및 GET /api/v1/mailboxes/{id}는 이제 mailbox_type("user" 또는 "shared")과 부울 is_shared를 반환하며, 공유 사서함에는 shared_member_count도 포함됩니다. 구성원 엔드포인트를 호출하기 전에 이 필드로 팀 받은 편지함과 일반 사서함을 구분하세요.

구성원 엔드포인트는 기존 mailboxes:read / mailboxes:write 범위를 재사용합니다. 별도의 공유 사서함 범위는 없습니다.

기본 메일 앱 액세스를 확인하려면 일반 구성원 사서함에 대해 GET /api/v1/mailboxes/{member_mailbox_id}/client-setup을 호출하세요. shared_mailboxes 객체는 지속적인 기본 액세스 준비 상태, 유효한 보내는 사람 준비 상태/이유, 정확한 받은 편지함/보낸 편지함/보관함/정크 경로 및 허용된 작업을 보고합니다. can_send는 할당된 회신 가능 권한이지 SMTP가 현재 준비되었다는 증거가 아닙니다. 이 엔드포인트는 비밀번호를 반환하지 않습니다. 공유 사서함 id로 호출하면 공유 주소가 직접 인증할 수 없으므로 422 direct_login_unavailable을 반환합니다.

구성원 제거, can_send 변경 또는 공유 사서함을 일반 사서함으로 변환하면 기본 액세스가 활성화된 경우 메일 서버 권한이 동기화됩니다. 503 native_access_sync_failed 응답은 재시도할 수 있으며 작업이 일부만 적용되는 대신 멤버십, 권한 또는 사서함 유형이 변경되지 않았음을 보장합니다.

사용 가능한 엔드포인트

Drive에는 별도의 참조 문서가 있으므로 여기서는 반복하지 않습니다. Drive API 개요를 참조하세요. 이전 버전과의 호환성을 위해 유지되는 계정 수준 SMTP 엔드포인트는 현재 목록이 아니라 도메인별 SMTP 라우팅에서 설명합니다.

Cloudflare 엔드포인트는 대시보드와 같은 흐름을 따릅니다. 토큰을 검증하고, 영역을 나열하고, 도메인을 연결하고, DNS 변경 사항을 미리 본 다음 적용합니다. /cloudflare/preview와 /cloudflare/apply 모두 도메인별로 두 가지 선택적 제어를 받습니다.

• included_records: 건드릴 레코드의 허용 목록이며 도메인 ID를 키로 사용합니다. { "123": ["mx_primary", "spf_record"] }. 제외한 레코드는 건너뛰므로 MX와 SPF만 적용하고 나중에 DKIM을 처리할 수 있습니다. 모든 레코드를 적용하려면 필드를 생략하세요.
• confirmed_conflicts: 미리 보기에서 이미 다른 값을 가진 레코드를 표시하면 여기에 해당 레코드 ID를 나열하여(동일한 { domain_id: [record_ids] } 형식) 교체를 승인합니다.

레코드 ID(mx_primary, spf_record, dkim_primary, dmarc_main, …)는 미리 보기 응답에서 직접 제공되므로 일반적인 에이전트는 먼저 미리 보기를 호출하고 원하는 ID를 적용 호출에 전달합니다.

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

도메인별 SMTP 라우팅과 계정 기본값

SMTP는 도메인별로 구성됩니다. 각 도메인은 관리형 플랫폼 전송, 저장된 SMTP 프로필(자체 제공업체, 여러 도메인에서 재사용 가능) 또는 "구성되지 않음"의 세 경로 중 하나를 선택하며, 계정 전체의 단일 기본값이 새 도메인의 초기 경로를 결정합니다.

도메인별 엔드포인트 (smtp:read / smtp:write):

경로 본문에 관한 몇 가지 참고 사항은 다음과 같습니다.

• smtp_mode=platform은 관리형 전송을 선택하고, smtp_mode=profile에는 smtp_connection_id가 필요하며, not_configured는 경로를 지웁니다.
• smtp_mode=inherit를 사용하면 계정 기본값이 바뀔 때마다 도메인이 해당 기본값을 실시간으로 따릅니다. 웹 UI는 항상 구체적인 경로를 기록하지만 백엔드는 여전히 inherit를 지원하므로 GET은 effective_smtp_mode를 반환하여 현재 inherit가 해석되는 값을 보여 줍니다.
• set_account_default: true는 대시보드의 계정 기본값으로 설정 토글에 해당하는 API 옵션입니다(새 도메인이 이 경로로 시작). apply_to_all: true는 모든 도메인에 적용 버튼에 해당합니다(모든 도메인을 이 경로로 한 번 전환).

계정 전체 기본값 엔드포인트 (smtp:read / smtp:write):

계정 기본값이었던 프로필을 삭제하면 기본값이 요금제 기준으로 재설정됩니다.

레거시 엔드포인트. 계정 수준 GET/PUT /api/v1/smtp 및 DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}는 이전 버전과의 호환성을 위해 유지되지만 더 이상 도메인별 라우팅을 제어하지 않습니다. 위의 도메인별 엔드포인트와 /smtp/default 엔드포인트를 사용하세요. 레거시 MCP 도구 get_smtp_config / update_smtp_config도 같은 이유로 지원 중단되었습니다.

White Label 브랜딩, 클라이언트 및 팀 액세스

브랜딩은 branding:read / branding:write를 사용하여 도메인별로 구성합니다. 도메인은 자체 브랜드(mode=custom)를 사용하거나 계정 기본값을 상속하거나(mode=inherit) 끌 수 있습니다. 활성 White Label 평가판 또는 유료 애드온이 필요합니다. 취소 후 표시된 유예 기간에는 소유자가 읽기 전용 복구 액세스를 유지합니다. 도메인의 dns_records를 읽고 반환된 레코드를 그대로 게시하세요. 예시에서 호스트 이름이나 CNAME 대상을 유추하지 마세요.

PATCH는 부분 병합이므로 생략된 필드는 유지됩니다. 현재 브랜딩이 꺼져 있다면 다시 활성화하도록 mode를 전달하세요. 사용자 지정 sender_email은 DKIM 키가 확인된 도메인에 있어야 합니다. mail_zone_enabled는 브랜드 자체 도메인에서 메일 앱과 DAV 동기화를 제공합니다. 단일 도메인이 아니라 브랜드에 속하므로 mode=custom 또는 scope=account_default가 필요하며, inherit 도메인은 422 inherited_brand를 반환합니다. 프로비저닝을 추적하고 준비된 DAV 주소만 사용하려면 mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url 및 mail_zone.dav_ready를 읽으세요. 전체 에이전트 워크플로는 White Label 브랜딩 API 및 MCP 가이드를 참조하세요.

계정 수준 White Label 영역은 /api/v1/white-label 아래에 13개 경로를 추가합니다. 상태와 설정 진행률, 실시간 액세스 카탈로그, 구성원 목록과 수명 주기 작업, 계정 활동 및 구성원별 작업/로그인 기록을 제공합니다. members:read, members:write 및 activity:read를 사용합니다. 액세스는 항상 계정 권한, 사용자의 현재 멤버십, 자격 증명 부여 및 도메인 제한의 교집합입니다. 경로 표와 상태 전환은 API 및 MCP로 White Label 팀 관리하기를 참조하세요.

OpenAPI 명세는 Postman, Insomnia 또는 코드 생성기로 가져올 수 있도록 /api/openapi.json에 제공됩니다.

빠른 해결 방법

• 401 "unauthenticated": Authorization: Bearer <token> 헤더가 있고 토큰이 취소되거나 만료되지 않았는지 확인하세요.
• 403 "plan_api_disabled": 요청한 범위가 요금제에 포함되지 않습니다. Nano는 Email Verifier를 제공하며 Drive Storage Add-on을 구매한 경우 Drive도 제공합니다. 나머지 API를 사용하려면 Starter 이상으로 업그레이드하세요.
• 403 "token_scope_blocked_by_plan": 토큰에 현재 요금제에서 제공되지 않는 범위가 있습니다. 토큰을 취소하고 허용된 범위로 새 토큰을 만드세요.
• 403 "scope_blocked_by_entitlement": 애드온이 비활성 상태이거나 작업이 유예 기간 중 쓰기이므로 저장된 White Label 권한을 사용할 수 없습니다. White Label을 다시 활성화한 다음 자격 증명을 재발급하거나 다시 승인하세요.
• 403 "scope_blocked_by_membership": 현재 구성원 역할이 요청한 작업보다 제한적입니다. 소유자에게 변경을 요청하세요. 다시 승인하는 것만으로는 멤버십을 확장할 수 없습니다.
• 422 "missing_idempotency_key": 엔드포인트 참조에서 지정한 쓰기 작업에 Idempotency-Key 헤더를 추가하세요.
• 403 "mailbox_sending_paused": 발신 메일이 소유자가 보낸 것처럼 보이지 않아 해당 사서함의 전송이 중지되었습니다. 일반적으로 비밀번호가 잘못된 사람의 손에 들어간 경우입니다. 읽기, 목록 조회 및 다른 모든 엔드포인트는 계속 작동하지만 전송만 거부되며 재시도로 해제되지 않습니다. 사서함 비밀번호를 변경해야 하며 이후 지원팀이 전송을 다시 켭니다. 이메일을 보낼 수 없는 이유를 참조하세요.
• 429 속도 제한: 다시 시도하기 전에 Retry-After 헤더에 지정된 시간만큼 기다리세요.

이메일 전송: 본문, 헤더, 배달 가능성

POST /api/v1/messages/send는 요청 형식 {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}를 받습니다.

• body.text와 body.html은 모두 선택 사항이지만 최소 하나는 필요합니다. body.text만 제공하면 <p> 단락을 사용하여 HTML 대안을 자동 생성하므로(빈 줄은 단락을 나누고 단일 줄바꿈은 <br>이 됨) 모든 최신 클라이언트에서 일반 이메일로 표시됩니다. 고정 폭 글꼴이 필요하면 리터럴 <pre>...</pre>를 body.html로 보내세요.
• headers는 사용자가 제공하는 발신 헤더의 선택적 객체입니다. 허용 목록은 List-Unsubscribe, List-Unsubscribe-Post, Reply-To 및 모든 X-* 사용자 지정 추적 헤더입니다. 다른 이름(From, Subject, Message-Id, Authentication-Results 등)은 플랫폼에서 관리되며 422로 거부됩니다. CR/LF가 포함된 값도 거부됩니다(헤더 삽입 방지). 값은 998자로 제한됩니다(RFC 2822).
• 대량/자동화 사용 사례에서는 List-Unsubscribe 설정과 계정 전체 auto_list_unsubscribe 토글에 관한 대량 발신자 배달 가능성 헤더 섹션을 참조하세요.