API와 MCP를 통한 이메일 전송률 및 반송 관리

TrekMail 대시보드는 각 도메인의 통계 탭에 다음 두 종류의 반송 데이터를 표시합니다.

1. 30일 요약: 발송, 전송 완료, 소프트 반송, 하드 반송 건수와 전송률 및 반송률.
2. 수신자별 목록: 특정 메시지가 실패한 이유를 확인할 수 있도록 수신 서버의 SMTP 상태 코드 및 응답과 함께 최근 발신 반송 50건을 보여 줍니다.

이제 두 데이터 모두 REST API와 MCP 서버에서 사용할 수 있습니다. 에이전트는 대시보드를 열지 않고도 반송 사유를 가져오고, 평판 상태를 요약하고, 목록 정리 워크플로에 데이터를 제공할 수 있습니다.

제공되는 데이터

세 항목 모두 domains:read가 필요합니다(메일함 범위 목록은 mailboxes:read 사용 가능). 읽기 전용이며 멱등성 키는 필요하지 않습니다.

API는 대시보드의 통계 카드와 동일한 전송률 데이터를 사용하므로 두 보기가 항상 일치합니다.

REST API: 빠른 예시

도메인 요약

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status는 대시보드가 표시하는 것과 동일한 세 단계 신호입니다.

• good: 반송률이 2% 미만입니다.
• warning: 반송률이 2%에서 5% 사이입니다.
• poor: 반송률이 5% 이상입니다. 발송 목록을 검토하고 정리하세요.

forwarding_bounces_excluded는 비율 계산에서 제외된 전달 관련 반송 수를 나타냅니다(대시보드와 마찬가지로 이러한 반송은 발신자 목록 문제가 아니라 라우팅 과정에서 발생한 결과로 처리됩니다).

수신자별 반송 목록

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

쿼리 매개변수

메일함 범위 목록

발신자별 평판을 조사하려면 하나의 메일함으로 범위를 제한하세요.

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

응답 형식은 도메인 엔드포인트와 동일합니다.

SMTP 응답의 개인정보 보호

TrekMail은 SMTP 응답을 반환하기 전에 내부 진단 정보를 제거합니다. 남은 메시지는 대시보드에서 계정 소유자에게 표시되는 메시지와 동일하며, 서버 내부 정보를 노출하는 것이 아니라 전송 문제를 진단하기 위한 것입니다.

MCP 도구

세 도구 모두 REST 엔드포인트와 동일한 매개변수를 받습니다. 읽기 전용이며 메일 또는 계정 설정을 변경하지 않습니다.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

대량 발신자용 전송률 헤더

마케팅 메일이나 구독 기반 대량 메일을 보내는 경우 주요 메일함 제공업체가 원클릭 수신 거부 헤더를 요구할 수 있습니다. Google은 대량 발신자 기준을 초과하는 발신자의 마케팅 및 구독 메시지에 이 규칙을 적용하며, 트랜잭션 메시지에는 원클릭 규칙을 적용하지 않습니다. 헤더를 첨부하는 방법은 두 가지입니다.

메시지별 설정(세부 제어). headers 필드를 통해 POST /api/v1/messages/send에 전달합니다.

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

headers 필드는 List-Unsubscribe, List-Unsubscribe-Post, Reply-To 및 모든 X-* 사용자 지정 추적 헤더로 구성된 작은 허용 목록을 받습니다. 헤더 삽입(CR/LF)과 관리형 헤더(From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature 등)는 422로 거부됩니다.

계정 전체 설정(한 번 설정). 이 계정의 모든 발신 메시지가 자동화된 경우 계정에서 auto_list_unsubscribe를 켤 수 있습니다. 활성화하면 플랫폼은 아직 이 헤더가 없는 모든 발신 메시지에 mailto 전용 List-Unsubscribe 헤더를 추가합니다. List-Unsubscribe-Post는 추가하지 않으므로 이 대체 방식은 RFC 8058 원클릭 수신 거부가 아닙니다. 제공업체 요구사항을 준수하는 원클릭 수신 거부를 제공하려면 위 예시와 같이 자체 HTTPS 수신 거부 엔드포인트와 함께 메시지별로 두 헤더를 모두 제공하세요. 호출자가 제공한 헤더가 항상 우선합니다. 이 설정은 기본적으로 꺼져 있으며 기존 계정은 변경되지 않습니다.

개인 간 일대일 메일에서는 이 설정을 꺼 두세요. 이 헤더가 있으면 Gmail이 발신자 옆에 수신 거부 버튼을 표시할 수 있으며, 이는 일반적으로 대화에 적합하지 않습니다.

AI 에이전트를 위한 패턴

이러한 엔드포인트로 다음과 같은 가치 높은 워크플로를 구성할 수 있습니다.

• 주간 평판 요약. 매주 월요일 계정의 모든 도메인에 대해 get_domain_deliverability를 호출하고 Slack 또는 Teams에 요약을 게시합니다. status가 warning 또는 poor인 도메인만 표시합니다.
• 반송 기반 목록 정리. list_domain_bounces?type=hard&days=14를 호출하고 recipient_email 중복을 제거한 다음 발송 목록에서 해당 주소를 억제합니다. 하드 반송은 일반적으로 수신자 주소가 더 이상 존재하지 않음을 의미하며, 재발송하면 전송률 여유를 낭비하게 됩니다.
• 발신자별 조사. 단일 메일함의 bounce_rate가 급증하면 해당 메일함에서 list_mailbox_bounces를 호출하고 smtp_status_code별로 그룹화합니다. 550 코드가 급증하면 주소 목록이 오래되었을 수 있고, 421 코드가 급증하면 수신 메일 서버가 전송 속도를 제한했을 수 있습니다.
• 고객 지원 조사. 사용자가 이메일이 도착하지 않았다고 신고하면 에이전트가 list_domain_bounces?recipient=<their-address>를 호출하도록 합니다. SMTP 응답은 가득 찬 수신자 메일함 비우기, 수신자 측 차단 해제 또는 DMARC 거부 수정과 같은 다음 조치를 알려 줄 수 있습니다.

버전 관리

이러한 엔드포인트는 나머지 v1 API와 동일한 버전 관리 계약을 따릅니다. 추가적인 변경만 허용하며, v2/ 네임스페이스 없이는 호환성을 깨뜨리는 필드 이름 변경을 하지 않습니다.