Mailtrap

공식

Mailtrap 이메일 API와 통합됩니다.

GitHub
63

Mailtrap MCP(으)로 무엇을 할 수 있나요?

  • 트랜잭션 이메일 보내기 — send-email을 통해 인라인 콘텐츠 또는 템플릿으로 이메일 전송을 요청하고, CC/BCC 및 사용자 정의 변수를 포함할 수 있습니다.
  • 이메일 템플릿 관리 — list-templates, create-template, update-template 또는 delete-template을 사용하여 재사용 가능한 이메일 디자인을 유지 관리합니다.
  • 전송 로그 확인 — 수신자, 상태 또는 날짜 같은 필터로 list-email-logs를 조회한 다음, get-email-log-message로 세부 정보를 확인합니다.
  • 샌드박스에서 이메일 테스트 — send-sandbox-email로 테스트 받은 편지함에 전송한 다음, get-sandbox-messages 및 show-sandbox-email-message로 메시지를 검토합니다.
  • 전송 성과 분석 — get-sending-stats를 통해 전달, 반송 및 참여율을 확인하고, 필요에 따라 도메인 또는 카테고리별로 세분화할 수 있습니다.
  • 전송 인프라 구성 — list-sending-domains를 관리하고, 도메인을 생성 또는 삭제하며, DNS 설정 지침을 검색합니다.

문서

TypeScript test NPM

MCP Mailtrap 서버

Mailtrap을 통해 샌드박스에서 이메일 전송 및 테스트를 위한 도구를 제공하는 MCP 서버입니다.

사전 요구 사항

이 MCP 서버를 사용하기 전에 다음을 수행해야 합니다:

  1. Mailtrap 계정 만들기
  2. 도메인 인증
  3. Mailtrap API 설정에서 API 토큰을 가져옵니다
  4. Mailtrap 계정 관리에서 계정 ID를 가져옵니다

필수 환경 변수:

  • MAILTRAP_API_TOKEN - 모든 기능에 필요합니다
  • MAILTRAP_ACCOUNT_ID - 템플릿, 통계, 이메일 로그, 샌드박스 목록/보기, 발송 도메인에 필요합니다. 전송 도구(send-email, send-sandbox-email, batch-send-* 도구)에는 선택 사항입니다.

선택 사항(대신 도구 매개변수로 전달 가능):

  • DEFAULT_FROM_EMAIL - from가 send-email, send-sandbox-email 또는 batch-send-* 도구에 제공되지 않을 때의 기본 발신자 이메일(base.from을 채웁니다). from 매개변수를 통해 호출별로 발신자를 전환할 수 있습니다.
  • MAILTRAP_SANDBOX_ID - sandbox_id이 제공되지 않을 때 샌드박스 도구의 기본 샌드박스 ID입니다. sandbox_id 매개변수를 통해 호출별로 샌드박스를 전환할 수 있습니다.
  • MAILTRAP_TEST_INBOX_ID - test_inbox_id이 제공되지 않을 때 샌드박스 도구의 기본 테스트 받은편지함 ID입니다. test_inbox_id 매개변수를 통해 호출별로 받은편지함을 전환할 수 있습니다. MAILTRAP_SANDBOX_ID의 레거시 별칭으로, 여전히 대체 수단으로 인정됩니다.
  • MAILTRAP_ORGANIZATION_ID - 조직 도구(list-sub-accounts, create-sub-account)에 필요합니다.
  • MAILTRAP_ORGANIZATION_API_TOKEN - 조직 범위 API 토큰입니다. 조직 도구에 필요합니다(MAILTRAP_API_TOKEN와 별개).

빠른 설치

Install in Cursor

Install with Node in VS Code

Smithery CLI

Smithery는 모든 AI 클라이언트와 호환되는 MCP 서버용 레지스트리 설치 프로그램이자 관리자입니다.

npx @smithery/cli install mailtrap

Smithery는 클라이언트 구성을 자동으로 처리하고 대화형 설정 프로세스를 제공합니다. 로컬에서 MCP 서버를 시작하는 가장 쉬운 방법입니다.

설정

Claude Desktop

MCPB를 사용하여 Mailtrap 서버를 설치하세요. 해당 파일은 Releases에서 찾을 수 있습니다.
Download .MCPB 파일을 다운로드하여 열어보세요. Claude Desktop이 있으면 파일을 열고 구성을 제안할 것입니다.

Claude Desktop 또는 Cursor

다음 구성을 추가하세요:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Node.js 관리를 위해 asdf을 사용하는 경우 실행 파일의 절대 경로를 사용해야 합니다(Mac 예시)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Claude Desktop 구성 파일 위치

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor 구성 파일 위치

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

수동으로 구성 변경

명령 팔레트에서 실행: Preferences: Open User Settings (JSON)

그런 다음 설정 파일에 다음 구성을 추가하세요:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] "env" 섹션을 변경한 후 MCP 서버를 다시 시작하는 것을 잊지 마세요.

MCP 번들(MCPB)

MCP 번들을 지원하는 호스트에 쉽게 설치하려면 .mcpb 번들 파일을 배포할 수 있습니다.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

이렇게 하면 저장소 manifest.json와 dist/의 빌드 산출물을 사용하여 mailtrap-mcp.mcpb이 생성됩니다.

사용법

구성이 완료되면 에이전트에게 이메일 전송 및 템플릿 관리를 요청할 수 있습니다. 예:

이메일 전송 작업:

  • "john.doe@example.com에게 제목 'Meeting Tomorrow'와 다가오는 회의에 대한 친절한 알림이 포함된 이메일을 보내줘."
  • "sarah@example.com에게 프로젝트 업데이트에 대해 이메일을 보내고 team@example.com의 팀을 CC에 포함시켜줘."
  • "환영 템플릿(uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96)을 변수 { name: 'Alex' }와 함께 new@example.com으로 보내줘."
  • "환영 이메일이 어떻게 보이는지 미리 보기 위해 test@example.com으로 제목 'Test Template'인 샌드박스 이메일을 보내줘."

이메일 로그(전달 디버깅):

  • "최근에 보낸 이메일 로그를 나열해줘."
  • "user@example.com으로 보낸 이메일의 로그를 보여줘."
  • "전달 상태를 확인하기 위해 ID abc-123-uuid의 이메일 로그 메시지를 가져와줘."

발송 통계:

  • "2025년 1월 발송 통계를 가져와줘."
  • "지난달 도메인별 전달률을 보여줘."
  • "2025-01-01부터 2025-01-31까지 카테고리별 이메일 통계는 무엇인가요?"

샌드박스 작업:

  • "내 샌드박스 받은편지함에서 모든 메시지를 가져와줘."
  • "샌드박스 메시지의 첫 페이지를 보여줘."
  • "내 샌드박스 받은편지함에서 'test'가 포함된 메시지를 검색해줘."
  • "ID 5159037506의 샌드박스 메시지 세부 정보를 보여줘."

템플릿 작업:

  • "내 Mailtrap 계정의 모든 이메일 템플릿을 나열해줘."
  • "제목이 'Welcome to our platform!'인 'Welcome Email'이라는 새 이메일 템플릿을 만들어줘."
  • "ID 12345 템플릿의 제목을 'Updated Welcome Message'로 변경해줘."
  • "ID 67890 템플릿을 삭제해줘."

발송 도메인:

  • "내 발송 도메인을 나열해줘."
  • "ID 3938 발송 도메인을 가져와줘."
  • "example.com용 발송 도메인을 만들어줘."
  • "발송 도메인 3938을 삭제해줘."
  • "DNS 설정 지침과 함께 발송 도메인 3938을 가져와줘."

사용 가능한 도구

send-email

Mailtrap을 통해 트랜잭션 이메일을 전송합니다. 인라인 콘텐츠(subject + text/html) 또는 템플릿 기반(template_uuid)의 두 가지 상호 배타적 모드를 지원합니다.

매개변수:

  • from (선택): { email, name? } 형식의 발신자(런타임에 이메일 문자열만 사용해도 허용됨). 제공되지 않으면 DEFAULT_FROM_EMAIL이 사용됩니다.
  • to (선택): { email, name? } 객체 배열의 수신자(런타임에 이메일 문자열만 또는 배열이 아닌 단일 주소도 허용됨). cc 또는 bcc이 제공되면 선택 사항입니다. to / cc / bcc 중 하나 이상에 수신자가 포함되어야 합니다.
  • cc (선택): { email, name? } 객체 배열의 CC 수신자(런타임에 이메일 문자열만도 허용됨).
  • bcc (선택): { email, name? } 객체 배열의 BCC 수신자(런타임에 이메일 문자열만도 허용됨).
  • subject (조건부): 이메일 제목 줄. 인라인 전송에 필요하며 template_uuid이 설정된 경우 생략해야 합니다.
  • text (조건부): 이메일 본문 텍스트. 인라인 전송에 필요하며(html과 함께 또는 대신) template_uuid이 설정된 경우 생략해야 합니다.
  • html (조건부): 이메일 본문의 HTML 버전. 인라인 전송에 필요하며(text과 함께 또는 대신) template_uuid이 설정된 경우 생략해야 합니다.
  • category (선택): 추적 및 분석을 위한 이메일 카테고리. template_uuid이 설정된 경우 생략해야 합니다.
  • template_uuid (선택): 인라인 콘텐츠 대신 Mailtrap 이메일 템플릿을 사용합니다. 설정된 경우 subject / text / html / category을 생략해야 합니다(Mailtrap API 기준).
  • template_variables (선택): template_uuid이 참조하는 템플릿에 대입되는 변수 객체. template_uuid과 함께만 허용됩니다.

batch-send-transactional-email

하나의 Mailtrap API 호출로 트랜잭션 이메일 배치를 전송합니다(기본 발송 스트림). 공유 필드는 base에, 수신자별 재정의는 requests[]에 들어갑니다. 각 요청에는 to, cc 또는 bcc을 통해 수신자가 최소 한 명 포함되어야 합니다. send-email과 동일한 인라인-템플릿 상호 배타 규칙이 적용되며, 기본값과 각 요청을 병합한 후 확인됩니다.

매개변수:

  • base (선택): 배치 전체에서 공유되는 필드가 있는 객체.
    • from (선택): { email, name? } 형식의 발신자(런타임에 이메일 문자열만도 허용됨). DEFAULT_FROM_EMAIL으로 대체됩니다.
    • reply_to (선택): 회신 주소.
    • subject / text / html / category (선택, 인라인 모드): 모든 요청의 기본 콘텐츠.
    • template_uuid / template_variables (선택, 템플릿 모드): 기본 템플릿 + 변수. 인라인 필드와 상호 배타적입니다.
    • custom_variables (선택): 기본 사용자 정의 변수(문자열 값).
    • headers (선택): 기본 사용자 정의 헤더.
  • requests (필수): 수신자별 메시지의 비어 있지 않은 배열. 각 항목에는 다음이 있습니다:
    • to (선택): { email, name? } 객체 배열의 수신자(런타임에 이메일 문자열만 또는 배열이 아닌 단일 주소도 허용됨). cc 또는 bcc이 제공되면 선택 사항입니다. to / cc / bcc 중 하나 이상에 수신자가 포함되어야 합니다.
    • cc, bcc, reply_to (선택).
    • 인라인(subject/text/html/category) 또는 템플릿(template_uuid/template_variables) 재정의. 생략된 필드는 해당 base 값으로 대체됩니다.
    • custom_variables, headers (선택).

batch-send-bulk-email

Mailtrap의 벌크 스트림 API를 통해 벌크 이메일 배치를 전송합니다. batch-send-transactional-email과 동일한 base + requests[] 구조, 검증 및 인라인-템플릿 규칙을 따릅니다. 유일한 차이점은 이 도구가 트랜잭션 엔드포인트 대신 벌크 엔드포인트를 통해 호출을 라우팅한다는 것입니다. 위의 매개변수를 참조하세요.

list-email-logs

선택적 페이지네이션 및 필터와 함께 전송된 이메일 로그(전달 기록)를 나열합니다. IDE에서 전달 문제를 디버깅하는 데 사용합니다.

매개변수:

  • search_after (선택): 이전 응답의 next_page_cursor에서 가져온 페이지네이션 커서
  • sent_after (선택): ISO 8601 날짜/시간. 이 시간 이후에 전송된 로그만
  • sent_before (선택): ISO 8601 날짜/시간. 이 시간 이전에 전송된 로그만
  • from_email (선택): 발신자 이메일로 필터링. from_operator과 함께 사용(기본값: ci_equal)
  • to_email (선택): 수신자 이메일로 필터링. to_operator과 함께 사용(기본값: ci_equal)
  • status (선택): 전달 상태로 필터링: delivered, not_delivered, enqueued, opted_out. status_operator과 함께 사용(기본값: equal)
  • subject (선택): 이메일 제목으로 필터링. subject_operator과 함께 사용(기본값: ci_contain). subject_operator: empty/not_empty를 사용하여 제목 존재 여부로 필터링합니다.
  • sending_domain_id (선택): 발송 도메인 ID(숫자)로 필터링. sending_domain_id_operator과 함께 사용(기본값: equal)
  • sending_stream (선택): 스트림으로 필터링: transactional 또는 bulk. sending_stream_operator과 함께 사용(기본값: equal)
  • events (선택): 이벤트 유형으로 필터링: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension. events_operator과 함께 사용(include_event / not_include_event)
  • clicks_count / opens_count (선택): 클릭/열기 횟수로 필터링. *_operator과 함께 사용: equal, greater_than, less_than
  • client_ip / sending_ip (선택): IP로 필터링. *_operator과 함께 사용: equal, not_equal, contain, not_contain
  • email_service_provider_response (선택): 공급자 응답 텍스트로 필터링. *_operator과 함께 사용(ci_contain 등)
  • email_service_provider (선택): 공급자(정확히 일치)로 필터링. *_operator과 함께 사용: equal, not_equal
  • recipient_mx (선택): 수신자 MX로 필터링. recipient_mx_operator과 함께 사용(ci_contain 등)
  • category (선택): 이메일 카테고리로 필터링. category_operator과 함께 사용: equal, not_equal

모든 매개변수는 선택 사항입니다.

get-email-log-message

ID(UUID)로 단일 이메일 로그 메시지를 가져옵니다: 읽기 쉬운 요약(보낸 사람, 받는 사람, 제목, 전송 시간, 상태, 카테고리, 스트림, 참여도, 전달 컨텍스트)과 상세 이벤트 기록. 선택적으로 include_content: true을 사용하면 Mailtrap이 원시 메시지 URL을 노출할 때 메시지 본문(HTML 및 일반 텍스트)도 로드하여 표시할 수 있습니다.

매개변수:

  • message_id (필수): 이메일 로그 메시지의 UUID (전송 응답 또는 이메일 로그 목록에서 가져옴). 메시지 ID를 찾으려면 list-email-logs를 사용하세요.
  • include_content (선택): true인 경우, 원본 EML을 가져와서 (raw_message_url가 있는 경우) 파싱된 HTML 및 일반 텍스트 본문 섹션을 추가합니다. show-sandbox-email-message와 유사합니다.

get-sending-stats

날짜 범위에 대한 이메일 전송 통계(전달, 반송, 열람, 클릭, 스팸 비율)를 가져옵니다. 선택적으로 도메인, 카테고리, 이메일 서비스 제공업체 또는 날짜별로 세분화할 수 있습니다. 편집기를 벗어나지 않고 전달률을 확인하세요.

매개변수:

  • start_date (필수): 통계 범위의 시작 날짜 (YYYY-MM-DD)
  • end_date (필수): 통계 범위의 종료 날짜 (YYYY-MM-DD)
  • breakdown (선택): 통계를 세분화하는 방식: aggregated (기본값), by_domain, by_category, by_email_service_provider 또는 by_date
  • sending_domain_ids (선택): 결과를 특정 발송 도메인 ID로 제한 (정수 배열)
  • sending_streams (선택): transactional 및/또는 bulk으로 제한 (문자열 배열)
  • categories (선택): 특정 이메일 카테고리로 제한 (문자열 배열)
  • email_service_providers (선택): 특정 제공업체로 제한 (예: Google, Yahoo, Outlook) (문자열 배열)

create-template

Mailtrap 계정에 새 이메일 템플릿을 생성합니다.

매개변수:

  • name (필수): 템플릿 이름
  • subject (필수): 이메일 제목 줄
  • html (또는 text 필수): 템플릿의 HTML 콘텐츠
  • text (또는 html 필수): 템플릿의 일반 텍스트 버전
  • category (선택): 템플릿 카테고리 (기본값: "General")

list-templates

Mailtrap 계정의 모든 이메일 템플릿을 나열합니다.

매개변수:

  • 필수 매개변수 없음

get-template

ID로 단일 이메일 템플릿을 가져옵니다. 제목, 카테고리, HTML/텍스트 본문을 포함합니다.

매개변수:

  • template_id (필수): 가져올 템플릿의 ID

update-template

기존 이메일 템플릿을 업데이트합니다.

매개변수:

  • template_id (필수): 업데이트할 템플릿의 ID
  • name (선택): 템플릿의 새 이름
  • subject (선택): 새 이메일 제목 줄
  • html (선택): 템플릿의 새 HTML 콘텐츠
  • text (선택): 템플릿의 새 일반 텍스트 버전
  • category (선택): 템플릿의 새 카테고리

[!NOTE] update-template를 호출하여 업데이트를 수행하려면 업데이트 가능한 필드(이름, 제목, html, 텍스트 또는 카테고리) 중 하나 이상을 제공해야 합니다.

delete-template

기존 이메일 템플릿을 삭제합니다.

매개변수:

  • template_id (필수): 삭제할 템플릿의 ID

send-sandbox-email

개발 및 테스트 목적으로 Mailtrap 테스트 수신함에 이메일을 전송합니다. 실제 수신자에게 이메일을 보내지 않고 이메일 템플릿을 테스트하는 데 적합합니다. send-email와 동일한 두 가지 모드 — 인라인 콘텐츠 또는 템플릿 기반 (template_uuid)을 지원합니다.

매개변수:

  • test_inbox_id (선택): Mailtrap 테스트 수신함 ID. MAILTRAP_TEST_INBOX_ID이 설정되지 않은 경우 필수입니다. 특정 수신함을 대상으로 하려면 호출 시 전달하세요.
  • from (선택): { email, name? } 형식의 발신자 (실행 시 일반 이메일 문자열도 허용됨). 제공되지 않으면 DEFAULT_FROM_EMAIL이 사용됩니다.
  • to (선택): { email, name? } 객체 배열 형태의 수신자 (배열 내 일반 이메일 문자열 또는 쉼표로 구분된 일반 이메일 문자열도 실행 시 허용됨). cc 또는 bcc가 제공된 경우 선택 사항입니다. to / cc / bcc 중 하나 이상에 수신자가 포함되어야 합니다.
  • cc (선택): { email, name? } 객체 배열 형태의 CC 수신자 (실행 시 일반 이메일 문자열도 허용됨).
  • bcc (선택): { email, name? } 객체 배열 형태의 BCC 수신자 (실행 시 일반 이메일 문자열도 허용됨).
  • subject (조건부): 이메일 제목 줄. 인라인 전송에 필수이며, template_uuid가 설정된 경우 생략해야 합니다.
  • text (조건부): 이메일 본문 텍스트. 인라인 전송에 (html와 함께 또는 대신) 필수이며, template_uuid이 설정된 경우 생략해야 합니다.
  • html (조건부): 이메일 본문의 HTML 버전. 인라인 전송에 (text와 함께 또는 대신) 필수이며, template_uuid이 설정된 경우 생략해야 합니다.
  • category (선택): 추적용 이메일 카테고리. template_uuid가 설정된 경우 생략해야 합니다.
  • template_uuid (선택): 인라인 콘텐츠 대신 Mailtrap 이메일 템플릿을 사용합니다. 설정된 경우 subject / text / html / category은 생략해야 합니다.
  • template_variables (선택): template_uuid가 참조하는 템플릿에 대입되는 변수 객체. template_uuid와 함께만 허용됩니다.

batch-send-sandbox-email

단일 API 호출로 Mailtrap 테스트 수신함에 이메일 배치를 전송합니다. 실제 수신자에게는 전달되지 않습니다. base + requests[] 형식, 검증 및 인라인-대-템플릿 규칙은 batch-send-transactional-email과 동일합니다 — 차이점은 이 도구가 단일 테스트 수신함에 대해 샌드박스 엔드포인트를 통해 호출을 라우팅한다는 것입니다.

매개변수:

  • sandbox_id (선택): Mailtrap 샌드박스(테스트 수신함) ID. MAILTRAP_SANDBOX_ID이 설정되지 않은 경우 필수입니다. 특정 샌드박스를 대상으로 하려면 호출 시 전달하세요.
  • base (선택), requests (필수): 위의 batch-send-transactional-email 참조.

[!NOTE] 샌드박스 도구의 경우 도구 호출에 test_inbox_id를 제공하거나 MAILTRAP_TEST_INBOX_ID 환경 변수를 설정하세요. test_inbox_id을 전달하여 호출별로 수신함을 전환할 수 있습니다. sandbox_id을 사용하는 도구는 MAILTRAP_SANDBOX_ID을 먼저 사용합니다.

get-sandbox-messages

Mailtrap 테스트 수신함에서 메시지 목록을 검색합니다. 테스트 중 샌드박스에 어떤 이메일이 수신되었는지 확인하는 데 유용합니다.

매개변수:

  • page (선택): 페이지네이션용 페이지 번호 (최소값: 1)
  • last_id (선택): 마지막 메시지 ID를 사용한 페이지네이션. 지정된 메시지 ID 이후의 메시지를 반환합니다 (최소값: 1)
  • search (선택): 메시지를 필터링할 검색어

[!NOTE] 모든 매개변수는 선택 사항입니다. 아무것도 제공되지 않으면 수신함의 첫 페이지 메시지가 반환됩니다. 기존 페이지네이션에는 page를, 커서 기반 페이지네이션에는 last_id를, 콘텐츠별 메시지 필터링에는 search를 사용하세요.

show-sandbox-email-message

Mailtrap 테스트 수신함에서 특정 이메일 메시지의 상세 정보와 콘텐츠를 표시합니다. HTML 및 텍스트 본문 콘텐츠를 포함합니다.

매개변수:

  • message_id (필수): 검색할 샌드박스 이메일 메시지의 ID

[!NOTE] 먼저 get-sandbox-messages을 사용하여 메시지 목록과 해당 ID를 가져온 다음, 이 도구를 사용하여 특정 메시지의 전체 콘텐츠를 확인하세요.

get-sandbox-project

ID로 샌드박스 프로젝트를 가져옵니다. 수신함과 이메일 수를 포함합니다.

매개변수:

  • project_id (필수): 가져올 프로젝트의 ID

update-sandbox-project

기존 샌드박스 프로젝트의 이름을 변경합니다.

매개변수:

  • project_id (필수): 업데이트할 프로젝트의 ID
  • name (필수): 프로젝트의 새 이름 (2–100자)

list-sandboxes

API 토큰이 모든 프로젝트에서 액세스할 수 있는 모든 샌드박스를 나열합니다.

매개변수:

  • 필수 매개변수 없음

mark-sandbox-as-read

샌드박스의 모든 메시지를 읽음으로 표시합니다.

매개변수:

  • sandbox_id (필수): 작업 대상 샌드박스의 ID

reset-sandbox-credentials

샌드박스의 SMTP 자격 증명을 재설정합니다. 새 사용자 이름/비밀번호를 반환합니다.

매개변수:

  • sandbox_id (필수): 작업 대상 샌드박스의 ID

enable-sandbox-email-address

샌드박스의 이메일 수신 주소를 활성화합니다 (SMTP를 통해 메시지를 샌드박스로 전달하는 Mailtrap 주소를 켭니다).

매개변수:

  • sandbox_id (필수): 작업 대상 샌드박스의 ID

reset-sandbox-email-address

샌드박스의 새 이메일 수신 주소를 생성합니다.

매개변수:

  • sandbox_id (필수): 작업 대상 샌드박스의 ID

forward-sandbox-message

샌드박스 메시지를 외부 이메일 주소로 전달합니다. 월간 전달 할당량에 포함됩니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 전달할 샌드박스 메시지의 ID
  • email (필수): 메시지를 전달할 이메일 주소

update-sandbox-message

샌드박스 메시지를 읽음 또는 읽지 않음으로 표시합니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 업데이트할 샌드박스 메시지의 ID
  • is_read (필수): true은 읽음으로 표시하고, false은 읽지 않음으로 표시합니다.

delete-sandbox-message

단일 샌드박스 메시지를 삭제합니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 삭제할 샌드박스 메시지의 ID

get-sandbox-message-spam-score

샌드박스 메시지에 대한 SpamAssassin 스팸 보고서(점수, 규칙, 전체 보고서)를 가져옵니다. include_spam_report: true의 show-sandbox-email-message에 대한 독립형 대안입니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-html-analysis

샌드박스 메시지에 대한 HTML 분석 보고서(클라이언트 호환성 점수, 문제 요소)를 가져옵니다. include_html_analysis: true의 show-sandbox-email-message에 대한 독립형 대안입니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-headers

샌드박스 메시지의 파싱된 메일 헤더를 가져옵니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-html

샌드박스 메시지의 렌더링된 HTML 본문을 가져옵니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-text

샌드박스 메시지의 일반 텍스트 본문을 가져옵니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-raw

샌드박스 메시지의 원본 MIME 형식 메시지(헤더 + 본문)를 가져옵니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-eml

메시지를 EML 파일 페이로드로 렌더링하여 가져옵니다 (티켓에 첨부하거나 다른 메일 클라이언트로 가져오기에 적합).

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-message-html-source

샌드박스 메시지의 렌더링되지 않은 HTML 소스를 가져옵니다 (CID-링크 재작성과 같은 Mailtrap 측 변환 이전의 HTML).

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

list-sandbox-attachments

샌드박스 메시지의 모든 첨부 파일을 나열합니다 (파일 이름, 콘텐츠 유형, 크기, 다운로드 경로).

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID으로 대체됩니다.
  • message_id (필수): 샌드박스 메시지의 ID

get-sandbox-attachment

단일 첨부 파일의 메타데이터와 다운로드 URL을 가져옵니다.

매개변수:

  • sandbox_id (선택): 샌드박스 ID. MAILTRAP_SANDBOX_ID로 대체됩니다.
  • message_id (필수): 첨부 파일이 포함된 샌드박스 메시지의 ID
  • attachment_id (필수): 가져올 첨부 파일의 ID

list-sending-domains

발송 도메인과 해당 도메인의 DNS 검증 상태를 나열합니다.

매개변수:

  • 필수 매개변수 없음

get-sending-domain

ID로 발송 도메인과 해당 도메인의 검증 상태(DNS 레코드 포함)를 가져옵니다. include_setup_instructions를 true로 설정하면 DNS 설정 지침을 선택적으로 포함할 수 있습니다.

매개변수:

  • sending_domain_id (필수): 발송 도메인 ID
  • include_setup_instructions (선택): true인 경우 응답에 DNS 설정 지침을 추가합니다. 기본값: false

create-sending-domain

새 발송 도메인을 생성합니다. 생성 후 DNS 레코드를 추가하여 도메인을 검증합니다(include_setup_instructions: true와 함께 get-sending-domain을 사용하여 레코드를 확인).

매개변수:

  • domain_name (필수): 도메인 이름(예: example.com)

delete-sending-domain

발송 도메인을 삭제합니다.

매개변수:

  • sending_domain_id (필수): 삭제할 발송 도메인 ID

send-sending-domain-setup-instructions

발송 도메인의 DNS 설정 지침을 지정된 주소로 이메일로 보냅니다. DNS 레코드를 DevOps 팀원에게 전달할 때 유용합니다.

매개변수:

  • sending_domain_id (필수): 발송 도메인 ID
  • email (필수): DNS 설정 지침을 보낼 이메일 주소

list-suppressions

차단 목록(하드 바운스, 스팸 신고, 구독 취소, 수동 가져오기)을 나열하거나 검색합니다. 호출당 최대 1000개의 결과를 반환합니다.

매개변수:

  • email (선택): 이메일 필터. 이 주소와 일치하는 차단 항목만 반환합니다.

delete-suppression

ID로 차단 항목을 삭제합니다. Mailtrap은 해당 이메일이 다시 차단되지 않는 한 이메일 전송을 재개합니다.

매개변수:

  • suppression_id (필수): 삭제할 차단 항목의 ID

list-webhooks

계정에 구성된 모든 웹훅을 나열합니다. 전체 웹훅 레코드를 JSON으로 반환합니다.

매개변수:

  • 필수 매개변수 없음

get-webhook

ID로 단일 웹훅을 가져옵니다. 전체 웹훅 레코드를 JSON으로 반환합니다. 참고: signing_secret는 여기에서 반환되지 않습니다 — create-webhook의 응답에서만 사용할 수 있습니다.

매개변수:

  • webhook_id (필수): 가져올 웹훅의 ID

create-webhook

웹훅을 생성합니다. 응답에는 웹훅 페이로드 서명 검증을 위한 signing_secret이 포함됩니다 — 이 비밀 값은 생성 시에만 반환되므로 지금 저장하세요. 분실한 경우 웹훅을 다시 생성하세요.

매개변수:

  • url (필수): Mailtrap이 웹훅 이벤트를 POST할 URL
  • webhook_type (필수): "email_sending", "audit_log" 또는 "inbound_receiving"
  • active (선택, boolean): 기본값은 true
  • payload_format (선택): "json" 또는 "jsonlines". 기본값은 "json"
  • sending_stream (선택, email_sending 전용): "transactional" 또는 "bulk"
  • event_types (선택, email_sending 전용): delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject 배열
  • domain_id (선택, email_sending 전용): 이 웹훅의 범위를 지정할 발송 도메인 ID
  • inbound_inbox_id (선택, inbound_receiving 전용): 웹훅이 연결된 인바운드 받은편지함의 ID. 생략하면 계정의 모든 받은편지함에 적용됩니다.

update-webhook

웹훅의 변경 가능한 필드를 업데이트합니다. webhook_type, sending_stream, domain_id은 생성 후 변경할 수 없습니다 — 해당 항목을 변경해야 하는 경우 웹훅을 다시 생성하세요.

매개변수:

  • webhook_id (필수): 업데이트할 웹훅의 ID
  • url (선택): 새 웹훅 URL
  • active (선택, boolean): 웹훅 활성화 또는 비활성화
  • payload_format (선택): "json" 또는 "jsonlines"
  • event_types (선택, email_sending 전용): delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject 배열
  • inbound_inbox_id (선택, inbound_receiving 전용): 웹훅이 연결된 인바운드 받은편지함의 ID

delete-webhook

ID로 웹훅을 영구 삭제합니다. 삭제된 웹훅 레코드를 반환합니다.

매개변수:

  • webhook_id (필수): 삭제할 웹훅의 ID

get-contact

ID 또는 이메일로 연락처를 가져옵니다. 전체 연락처 레코드(목록 멤버십, 상태, 사용자 정의 필드)를 반환합니다.

매개변수:

  • contact_identifier (필수): 연락처 ID 또는 이메일 주소

create-contact

새 연락처를 생성합니다.

매개변수:

  • email (필수): 이메일 주소
  • fields (선택): 병합 태그로 키가 지정된 사용자 정의 필드 값(예: first_name). 문자열, 숫자 또는 boolean 값
  • list_ids (선택): 이 연락처를 구독시킬 연락처 목록의 ID
  • unsubscribed (선택, boolean): unsubscribed 상태로 연락처 생성

update-contact

ID 또는 이메일로 식별된 기존 연락처를 업데이트합니다. list_ids은 연락처의 전체 멤버십 집합을 대체합니다. list_ids_included/list_ids_excluded은 나머지를 건드리지 않고 추가/제거합니다.

매개변수:

  • contact_identifier (필수): 연락처 ID 또는 이메일
  • email (선택): 새 이메일 주소
  • fields (선택): 병합 태그로 키가 지정된 사용자 정의 필드 값
  • list_ids (선택): 멤버십 집합을 이 정확한 목록으로 대체
  • list_ids_included (선택): 추가할 목록 ID(추가적)
  • list_ids_excluded (선택): 제거할 목록 ID
  • unsubscribed (선택, boolean): unsubscribed(true) 또는 subscribed(false)로 설정

delete-contact

ID 또는 이메일로 연락처를 영구 삭제합니다. API가 응답하는 경우 삭제된 연락처 레코드를 반환하고, 그렇지 않은 경우 확인 페이로드를 반환합니다.

매개변수:

  • contact_identifier (필수): 연락처 ID 또는 이메일

create-contact-event

연락처(ID 또는 이메일)에 대한 연락처 이벤트를 기록합니다. 연락처 목록 자동화를 트리거하는 데 사용됩니다.

매개변수:

  • contact_identifier (필수): 연락처 ID 또는 이메일
  • name (필수): 이벤트 이름(자동화 트리거와 일치)
  • params (필수): 임의의 키/값 쌍 객체. 값은 문자열, 숫자, boolean 또는 null일 수 있습니다.

list-contact-lists

계정의 모든 연락처 목록을 나열합니다.

매개변수:

  • search (선택): 이름으로 연락처 목록 필터링(대소문자 구분 없음), 예: news

get-contact-list

ID로 연락처 목록을 가져옵니다.

매개변수:

  • list_id (필수): 가져올 연락처 목록의 ID

create-contact-list

새 연락처 목록을 생성합니다.

매개변수:

  • name (필수): 새 목록의 이름

update-contact-list

기존 연락처 목록의 이름을 변경합니다.

매개변수:

  • list_id (필수): 연락처 목록의 ID
  • name (필수): 목록의 새 이름

delete-contact-list

ID로 연락처 목록을 영구 삭제합니다.

매개변수:

  • list_id (필수): 삭제할 연락처 목록의 ID

list-contact-fields

계정의 모든 연락처 필드 정의를 나열합니다.

매개변수:

  • 필수 매개변수 없음

get-contact-field

ID로 연락처 필드 정의를 가져옵니다.

매개변수:

  • field_id (필수): 연락처 필드의 ID

create-contact-field

새 연락처 필드 정의를 생성합니다. merge_tag은 계정 내에서 고유해야 하며 템플릿 변수의 플레이스홀더 이름으로 사용됩니다.

매개변수:

  • name (필수): 표시 이름(예: "이름")
  • merge_tag (필수): 고유 플레이스홀더 이름(예: first_name)
  • data_type (필수): text, number, boolean, date 중 하나

update-contact-field

연락처 필드 정의를 업데이트합니다. name, merge_tag, data_type의 모든 조합을 변경할 수 있습니다.

매개변수:

  • field_id (필수): 연락처 필드의 ID
  • name (선택): 새 표시 이름
  • merge_tag (선택): 새 병합 태그(고유해야 함)
  • data_type (선택): text, number, boolean, date 중 하나

delete-contact-field

ID로 연락처 필드 정의를 영구 삭제합니다.

매개변수:

  • field_id (필수): 삭제할 연락처 필드의 ID

create-contact-import

연락처를 대량 가져옵니다. 가져오기 작업 레코드를 반환합니다. get-contact-import로 상태를 폴링합니다.

매개변수:

  • contacts (필수): 연락처 항목 배열. 각 항목에는 다음이 필요합니다:
    • email (필수): 연락처 이메일 주소
    • fields (선택): 병합 태그로 키가 지정된 사용자 정의 필드 값(문자열 또는 숫자 값)
    • list_ids_included (선택): 연락처를 추가할 목록 ID
    • list_ids_excluded (선택): 연락처를 제거할 목록 ID

get-contact-import

연락처 가져오기 작업의 상태(생성됨/시작됨/완료됨/실패함)와 생성/업데이트/초과 횟수를 가져옵니다.

매개변수:

  • import_id (필수): 연락처 가져오기 작업의 ID

create-contact-export

AND 결합 필터 집합과 일치하는 연락처를 내보냅니다. 내보내기 작업 레코드를 반환합니다. status가 finished가 되면 get-contact-export로 상태를 폴링하여 다운로드 URL을 가져옵니다.

매개변수:

  • filters (필수): 필터 객체 배열. 각 항목에는 다음이 있습니다:
    • name (필수): 필터링할 필드(list_id, subscription_status, email 등)
    • operator (필수): equal, not_equal, contains, not_contains, is_empty, is_not_empty 중 하나
    • value (필수): 비교 값(문자열, 숫자, boolean 또는 배열)

get-contact-export

연락처 내보내기 작업의 상태를 가져옵니다. status가 finished이 되면 url 필드에 CSV 다운로드 링크가 포함됩니다.

매개변수:

  • export_id (필수): 연락처 내보내기 작업의 ID

list-accounts

현재 API 토큰이 액세스할 수 있는 Mailtrap 계정을 각 계정의 액세스 수준과 함께 나열합니다.

매개변수:

  • 필수 매개변수 없음

get-billing-usage

계정의 현재 청구 주기 사용량을 가져옵니다: 발송 및 테스트 플랜, 한도, 현재 횟수.

매개변수:

  • 필수 매개변수 없음

list-account-accesses

계정의 계정 액세스(사용자, 초대, API 토큰)를 나열합니다. 선택적 필터로 결과를 특정 리소스로 좁힐 수 있습니다. 계정 관리자/소유자 권한이 필요합니다.

매개변수:

  • domain_uuids (선택): 발송 도메인 UUID로 필터링(문자열 배열)
  • inbox_ids (선택): 샌드박스 받은편지함 ID로 필터링(문자열 배열)
  • project_ids (선택): 샌드박스 프로젝트 ID로 필터링(문자열 배열)

remove-account-access

ID로 계정 액세스를 제거합니다. User 지정자의 경우 권한을 취소하고, Invite 또는 ApiToken 지정자의 경우 지정자를 완전히 제거합니다. 관리자/소유자 권한이 필요합니다.

매개변수:

  • account_access_id (필수): 제거할 액세스 레코드의 ID

get-permission-resources

API 토큰이 관리자 액세스 권한을 가진 모든 리소스(받은편지함, 프로젝트, 도메인, 청구, 계정)를 계층별로 중첩하여 가져옵니다.

매개변수:

  • 필수 매개변수 없음

bulk-update-permissions

단일 계정 액세스에 대한 권한을 대량 생성, 업데이트 또는 삭제합니다. 기존 (resource_type, resource_id) 쌍은 업데이트되고 새 쌍은 생성됩니다. 항목에 destroy: true을 설정하면 제거됩니다.

매개변수:

  • account_access_id (필수): 대상 계정 액세스 ID
  • permissions (필수): 권한 항목 배열. 각 항목은 다음을 포함합니다:
    • resource_id (필수): 리소스 ID (숫자 또는 문자열)
    • resource_type (필수): account, project, inbox, domain, billing 중 하나
    • access_level (선택): admin/100 또는 viewer/10
    • destroy (선택, boolean): true이면 이 권한을 생성/업데이트하는 대신 제거합니다

list-api-tokens

계정의 모든 API 토큰을 나열합니다.

매개변수:

  • 필수 매개변수 없음

create-api-token

새 API 토큰을 생성합니다. 응답에는 비밀 token 값이 포함됩니다 — 전체 토큰이 반환되는 것은 유일한 경우이므로 즉시 저장하세요. 분실한 경우 토큰을 다시 생성해야 합니다.

매개변수:

  • name (필수): 토큰의 표시 이름
  • resources (선택): 토큰 범위를 지정할 리소스 권한 배열. 각 항목은 다음을 포함합니다:
    • resource_type (필수): account, project, inbox, domain, billing 중 하나
    • resource_id (필수): 리소스 ID
    • access_level (필수): 100 (관리자) 또는 10 (뷰어)

get-api-token

ID로 API 토큰을 조회합니다. 메타데이터만 반환합니다 — 비밀 토큰 값은 여기서 반환되지 않습니다 (create-api-token / reset-api-token에서만 반환).

매개변수:

  • api_token_id (필수): API 토큰 ID

reset-api-token

ID로 API 토큰을 재설정(교체)합니다. 응답에는 새 비밀 token 값이 포함됩니다 — 이 호출에서만 반환되므로 즉시 저장하세요. 이전 토큰은 무효화됩니다.

매개변수:

  • api_token_id (필수): 재설정할 API 토큰 ID

delete-api-token

ID로 API 토큰을 영구 삭제합니다. 삭제 후에는 해당 토큰으로 더 이상 인증할 수 없습니다.

매개변수:

  • api_token_id (필수): 삭제할 API 토큰 ID

list-sub-accounts

조직의 하위 계정을 나열합니다. MAILTRAP_ORGANIZATION_ID 환경 변수와 하위 계정 관리 권한이 필요합니다.

매개변수:

  • 필수 매개변수 없음

create-sub-account

조직 아래에 새 하위 계정을 생성합니다. MAILTRAP_ORGANIZATION_ID 환경 변수와 하위 계정 관리 권한이 필요합니다.

매개변수:

  • name (필수): 새 하위 계정의 표시 이름

list-inbound-folders

계정의 모든 인바운드 폴더를 나열합니다. 형식화된 요약을 반환합니다.

매개변수:

  • 필수 매개변수 없음

get-inbound-folder

ID로 단일 인바운드 폴더를 조회합니다. 전체 폴더 레코드를 JSON으로 반환합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID

create-inbound-folder

새 인바운드 폴더를 생성합니다.

매개변수:

  • name (필수): 폴더 이름

update-inbound-folder

인바운드 폴더 이름을 변경합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID
  • name (필수): 새 폴더 이름

delete-inbound-folder

인바운드 폴더와 그 안의 모든 인박스를 영구 삭제합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID

list-inbound-inboxes

인바운드 폴더의 모든 인박스를 나열합니다. 형식화된 요약을 반환합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID

get-inbound-inbox

ID로 단일 인바운드 인박스를 조회합니다. 전체 인박스 레코드를 JSON으로 반환합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID
  • inbox_id (필수): 인박스 ID

create-inbound-inbox

폴더에 새 인바운드 인박스를 생성합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID
  • name (필수): 인박스 이름
  • domain_id (선택): 사용자 지정 발신 도메인에 연결 (catch-all 인박스). Mailtrap 호스팅 인박스의 경우 생략

update-inbound-inbox

인바운드 인박스 이름을 변경합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID
  • inbox_id (필수): 인박스 ID
  • name (필수): 새 인박스 이름

delete-inbound-inbox

인바운드 인박스를 영구 삭제합니다.

매개변수:

  • folder_id (필수): 인바운드 폴더 ID
  • inbox_id (필수): 인박스 ID

list-inbound-messages

인바운드 인박스의 수신 메시지를 나열합니다 (커서 페이지네이션). 더 많은 결과가 있을 때 다음 페이지 힌트와 함께 형식화된 요약을 반환합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • last_id (선택): 이전 응답의 last_id에서 가져온 페이지네이션 커서

get-inbound-message

전체 본문과 첨부 파일 다운로드 URL이 포함된 단일 인바운드 메시지를 조회합니다. 전체 메시지 레코드를 JSON으로 반환합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • message_id (필수): 메시지 ID

delete-inbound-message

인바운드 메시지를 영구 삭제합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • message_id (필수): 메시지 ID

reply-to-inbound-message

인바운드 메시지에 답장합니다 (원래 발신자에게 전송). 실제 이메일을 전송합니다. 주소는 이메일 문자열 또는 { email, name? }를 허용합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • message_id (필수): 답장할 메시지 ID
  • text / html (최소 하나 권장): 답장 본문
  • from (선택): 발신자. Mailtrap 호스팅 인박스에서는 거부됨; 사용자 지정 도메인 인박스에서는 필수
  • cc / bcc / reply_to (선택): 추가 주소
  • category (선택): 메시지 카테고리
  • attachments (선택): { content (base64), filename, type?, disposition?, content_id? } 배열
  • headers / custom_variables (선택): 문자열 값 객체

reply-all-to-inbound-message

인바운드 메시지에 답장하고 원본의 다른 수신자들을 참조로 포함합니다. 실제 이메일을 전송합니다. reply-to-inbound-message과 동일한 매개변수입니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • message_id (필수): 답장할 메시지 ID
  • reply-to-inbound-message과 동일한 선택적 전송 필드 포함

forward-inbound-message

인바운드 메시지를 새 수신자에게 전달합니다. 실제 이메일을 전송합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • message_id (필수): 전달할 메시지 ID
  • to (필수): 최소 한 명의 수신자 (이메일 문자열 또는 { email, name? }, 또는 배열)
  • reply-to-inbound-message과 동일한 선택적 전송 필드 포함

list-inbound-threads

인바운드 인박스의 대화 스레드를 나열합니다 (커서 페이지네이션). 더 많은 결과가 있을 때 다음 페이지 힌트와 함께 형식화된 요약을 반환합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • last_id (선택): 이전 응답의 last_id에서 가져온 페이지네이션 커서

get-inbound-thread

메시지가 포함된 단일 인바운드 스레드를 조회합니다 (오래된 순). 전체 스레드 레코드를 JSON으로 반환합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • thread_id (필수): 스레드 ID

delete-inbound-thread

인바운드 스레드를 영구 삭제합니다.

매개변수:

  • inbox_id (필수): 인박스 ID
  • thread_id (필수): 스레드 ID

개발

  1. 저장소를 클론합니다:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. 의존성을 설치합니다:
npm install

Claude Desktop 또는 Cursor로 구성

[!TIP] 구성 파일의 위치는 Setup 섹션을 참조하세요.

다음 구성을 추가합니다:

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

asdf로 Node.js를 관리하는 경우 실행 파일의 절대 경로를 사용해야 합니다:

(Mac 예시)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] 구성 파일의 위치는 Setup 섹션을 참조하세요.

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

테스트

실제 Mailtrap에 대해 도구 실행

실제 Mailtrap 계정에 대해 도구를 엔드투엔드로 실행하는 두 가지 방법이 있습니다: 대화형 탐색을 위한 MCP Inspector 브라우저 UI, 또는 셸에서 일회성 호출을 위한 CLI 모드입니다.

두 방법 모두 먼저 번들을 빌드해야 합니다:

npm run build

그리고 셸에 MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID를 내보내야 합니다 (mcp:cli 스크립트가 둘 다 생성된 서버로 전달합니다).

브라우저 UI

npm run dev

Inspector는 http://localhost:6274과 같은 URL을 출력합니다. 이를 열고 Tools 탭으로 전환한 후 도구(예: get-template)를 선택하고 매개변수를 JSON으로 채운 다음 Run을 클릭합니다. Mailtrap 응답이 아래 패널에 표시됩니다.

CLI

UI 없이 일회성 호출을 하려면 npm run mcp:cli을 사용하세요. npm이 그대로 전달하도록 -- 뒤에 Inspector의 CLI 플래그를 전달합니다:

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

MCPB 서버 실행

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] MCP Inspector로 개발하는 경우:

npm run dev:mcpb

오류 처리

이 서버는 MCP 규칙에 맞춘 구조화된 오류 처리를 사용합니다:

  • VALIDATION_ERROR: 입력 검증 실패
  • CONFIGURATION_ERROR: 구성 누락 또는 잘못됨
  • EXECUTION_ERROR: 런타임 실행 오류
  • TIMEOUT: 작업 시간 초과 (기본 30초)

오류에는 실행 가능한 메시지가 포함되며 구조화된 형태로 기록됩니다.

보안

  • Zod 스키마를 통한 입력 검증
  • 환경 변수의 안전한 처리
  • 작업 시간 초과 보호 (30초)
  • 오류 출력에서 민감한 정보 정리

로깅

수준이 있는 구조화된 JSON 로그: INFO, WARN, ERROR, DEBUG.

DEBUG=true를 설정하여 디버그 로깅을 활성화합니다.

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

중요: 서버는 로그를 stderr에 기록하므로 stdout은 JSON-RPC 프레임 전용으로 유지됩니다. 이렇게 하면 로그가 섞여 호스트가 JSON 파싱 오류를 겪는 것을 방지합니다.

jq을 사용한 로그 분석 예시:

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

문제 해결

일반적인 문제:

  1. API 토큰 누락: MAILTRAP_API_TOKEN이 설정되어 있는지 확인
  2. 샌드박스가 작동하지 않음: 도구 호출에 test_inbox_id을 제공하거나 MAILTRAP_TEST_INBOX_ID 환경 변수를 설정
  3. 시간 초과 오류: 네트워크 연결 및 Mailtrap API 상태 확인
  4. 검증 오류: 모든 필수 필드가 제공되었는지 확인

기여

버그 리포트와 풀 리퀘스트는 GitHub에서 환영합니다. 이 프로젝트는 안전하고 환영하는 협업 공간을 목표로 하며, 기여자는 행동 강령을 준수해야 합니다.

라이선스

이 패키지는 MIT License 조건에 따라 오픈 소스로 제공됩니다.

행동 강령

Mailtrap 프로젝트의 코드베이스, 이슈 트래커, 채팅방 및 메일링 리스트에서 상호작용하는 모든 사람은 행동 강령을 따를 것으로 기대됩니다.