Mailtrap

chính thức

Tích hợp với Mailtrap Email API.

GitHub
63

Bạn có thể làm gì với Mailtrap MCP?

  • Gửi email giao dịch — Yêu cầu gửi email qua send-email với nội dung trực tiếp hoặc mẫu, bao gồm CC/BCC và biến tùy chỉnh.
  • Quản lý mẫu email — Sử dụng list-templates, create-template, update-template hoặc delete-template để duy trì các thiết kế email tái sử dụng.
  • Kiểm tra nhật ký gửi — Truy vấn list-email-logs với bộ lọc như người nhận, trạng thái hoặc ngày, sau đó xem chi tiết bằng get-email-log-message.
  • Kiểm thử email trong môi trường sandbox — Gửi đến hộp thư kiểm thử qua send-sandbox-email, sau đó xem lại tin nhắn bằng get-sandbox-messages và show-sandbox-email-message.
  • Phân tích hiệu suất gửi — Lấy tỷ lệ gửi thành công, bị trả lại và tương tác qua get-sending-stats, tùy chọn phân tích theo tên miền hoặc danh mục.
  • Cấu hình hạ tầng gửi — Quản lý list-sending-domains, tạo hoặc xóa tên miền, và lấy hướng dẫn thiết lập DNS.

Tài liệu

TypeScript test NPM

Máy chủ MCP Mailtrap

Máy chủ MCP cung cấp các công cụ để gửi và kiểm thử trong sandbox thông qua Mailtrap.

Điều kiện tiên quyết

Trước khi sử dụng máy chủ MCP này, bạn cần:

  1. Tạo tài khoản Mailtrap
  2. Xác minh tên miền của bạn
  3. Lấy API token từ cài đặt API Mailtrap
  4. Lấy ID tài khoản từ trang quản lý tài khoản Mailtrap

Biến môi trường bắt buộc:

  • MAILTRAP_API_TOKEN - Bắt buộc cho mọi chức năng
  • MAILTRAP_ACCOUNT_ID - Bắt buộc cho mẫu, thống kê, nhật ký email, danh sách/hiển thị sandbox và tên miền gửi thư. Chỉ tùy chọn cho các công cụ gửi (send-email, send-sandbox-email và các công cụ batch-send-*).

Tùy chọn (có thể truyền dưới dạng tham số công cụ thay thế):

  • DEFAULT_FROM_EMAIL - Email người gửi mặc định khi from không được cung cấp cho send-email, send-sandbox-email hoặc các công cụ batch-send-* (nơi nó điền vào base.from). Cho phép chuyển đổi người gửi theo từng lệnh gọi thông qua tham số from.
  • MAILTRAP_SANDBOX_ID - ID sandbox mặc định cho các công cụ sandbox khi sandbox_id không được cung cấp. Cho phép chuyển đổi giữa các sandbox theo từng lệnh gọi thông qua tham số sandbox_id.
  • MAILTRAP_TEST_INBOX_ID - ID hộp thư kiểm thử mặc định cho các công cụ sandbox khi test_inbox_id không được cung cấp. Cho phép chuyển đổi giữa các hộp thư theo từng lệnh gọi thông qua tham số test_inbox_id. Bí danh kế thừa cho MAILTRAP_SANDBOX_ID, vẫn được hỗ trợ như một phương án dự phòng.
  • MAILTRAP_ORGANIZATION_ID - Bắt buộc cho các công cụ tổ chức (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - API token phạm vi tổ chức. Bắt buộc cho các công cụ tổ chức (tách biệt với MAILTRAP_API_TOKEN).

Cài đặt nhanh

Install in Cursor

Install with Node in VS Code

Smithery CLI

Smithery là trình cài đặt và quản lý registry cho các máy chủ MCP, hoạt động với mọi ứng dụng AI.

npx @smithery/cli install mailtrap

Smithery tự động xử lý cấu hình ứng dụng và cung cấp quy trình thiết lập tương tác. Đây là cách dễ nhất để bắt đầu với các máy chủ MCP cục bộ.

Thiết lập

Claude Desktop

Sử dụng MCPB để cài đặt máy chủ Mailtrap. Bạn có thể tìm thấy các tệp này trong Releases.
Tải xuống tệp .MCPB và mở nó. Nếu bạn có Claude Desktop - nó sẽ mở tệp và đề xuất cấu hình.

Claude Desktop hoặc Cursor

Thêm cấu hình sau:

{
  "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"
      }
    }
  }
}

Nếu bạn đang sử dụng asdf để quản lý Node.js, bạn phải sử dụng đường dẫn tuyệt đối đến tệp thực thi (ví dụ cho 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"
      }
    }
  }
}

Vị trí tệp cấu hình Claude Desktop

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Vị trí tệp cấu hình Cursor

Mac: ~/.cursor/mcp.json

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

VS Code

Thay đổi cấu hình thủ công

Chạy trong Command Palette: Preferences: Open User Settings (JSON)

Sau đó, trong tệp cài đặt, thêm cấu hình sau:

{
  "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] Đừng quên khởi động lại máy chủ MCP của bạn sau khi thay đổi phần "env".

MCP Bundle (MCPB)

Để cài đặt dễ dàng trên các máy chủ hỗ trợ MCP Bundles, bạn có thể phân phối tệp bundle .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

Thao tác này tạo mailtrap-mcp.mcpb bằng cách sử dụng kho lưu trữ manifest.json và các tạo phẩm đã xây dựng trong dist/.

Cách sử dụng

Sau khi được cấu hình, bạn có thể yêu cầu agent gửi email và quản lý mẫu, ví dụ:

Thao tác gửi email:

  • "Gửi email đến john.doe@example.com với tiêu đề 'Meeting Tomorrow' và lời nhắc thân thiện về cuộc họp sắp tới của chúng ta."
  • "Gửi email cho sarah@example.com về cập nhật dự án, và CC cho nhóm tại team@example.com"
  • "Gửi mẫu chào mừng (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) đến new@example.com với các biến { name: 'Alex' }"
  • "Gửi email sandbox đến test@example.com với tiêu đề 'Test Template' để xem trước email chào mừng của chúng ta trông như thế nào"

Nhật ký email (gỡ lỗi gửi thư):

  • "Liệt kê nhật ký email đã gửi gần đây của tôi"
  • "Hiển thị nhật ký email cho các email đã gửi đến user@example.com"
  • "Lấy thông điệp nhật ký email cho ID abc-123-uuid để kiểm tra trạng thái gửi"

Thống kê gửi thư:

  • "Lấy thống kê gửi thư cho tháng 1 năm 2025"
  • "Hiển thị tỷ lệ gửi thành công phân theo tên miền cho tháng trước"
  • "Thống kê email của tôi theo danh mục từ 2025-01-01 đến 2025-01-31 là gì?"

Thao tác Sandbox:

  • "Lấy tất cả thông điệp từ hộp thư sandbox của tôi"
  • "Hiển thị trang đầu tiên của các thông điệp sandbox"
  • "Tìm kiếm các thông điệp chứa 'test' trong hộp thư sandbox của tôi"
  • "Hiển thị chi tiết thông điệp sandbox có ID 5159037506"

Thao tác mẫu:

  • "Liệt kê tất cả mẫu email trong tài khoản Mailtrap của tôi"
  • "Tạo mẫu email mới có tên 'Welcome Email' với tiêu đề 'Welcome to our platform!'"
  • "Cập nhật mẫu có ID 12345 để đổi tiêu đề thành 'Updated Welcome Message'"
  • "Xóa mẫu có ID 67890"

Tên miền gửi thư:

  • "Liệt kê các tên miền gửi thư của tôi"
  • "Lấy tên miền gửi thư có ID 3938"
  • "Tạo tên miền gửi thư cho example.com"
  • "Xóa tên miền gửi thư 3938"
  • "Lấy tên miền gửi thư 3938 kèm hướng dẫn thiết lập DNS"

Các công cụ có sẵn

send-email

Gửi email giao dịch qua Mailtrap. Hỗ trợ hai chế độ loại trừ lẫn nhau — nội dung nội tuyến (subject + text/html) hoặc dựa trên mẫu (template_uuid).

Tham số:

  • from (tùy chọn): Người gửi dưới dạng { email, name? } (chuỗi email trần cũng được chấp nhận khi chạy). Nếu không được cung cấp, DEFAULT_FROM_EMAIL sẽ được sử dụng.
  • to (tùy chọn): Mảng người nhận dưới dạng đối tượng { email, name? } (chuỗi email trần hoặc một địa chỉ không phải mảng cũng được chấp nhận khi chạy). Tùy chọn nếu cc hoặc bcc được cung cấp; ít nhất một trong số to / cc / bcc phải chứa người nhận.
  • cc (tùy chọn): Mảng người nhận CC dưới dạng đối tượng { email, name? } (chuỗi email trần cũng được chấp nhận khi chạy).
  • bcc (tùy chọn): Mảng người nhận BCC dưới dạng đối tượng { email, name? } (chuỗi email trần cũng được chấp nhận khi chạy).
  • subject (có điều kiện): Dòng tiêu đề email. Bắt buộc cho gửi nội tuyến; phải bỏ qua khi template_uuid được thiết lập.
  • text (có điều kiện): Văn bản nội dung email. Bắt buộc (cùng với hoặc thay cho html) cho gửi nội tuyến; phải bỏ qua khi template_uuid được thiết lập.
  • html (có điều kiện): Phiên bản HTML của nội dung email. Bắt buộc (cùng với hoặc thay cho text) cho gửi nội tuyến; phải bỏ qua khi template_uuid được thiết lập.
  • category (tùy chọn): Danh mục email để theo dõi và phân tích. Phải bỏ qua khi template_uuid được thiết lập.
  • template_uuid (tùy chọn): Sử dụng mẫu email Mailtrap thay vì nội dung nội tuyến. Khi được thiết lập, subject / text / html / category phải được bỏ qua (theo Mailtrap API).
  • template_variables (tùy chọn): Đối tượng các biến được thay thế vào mẫu được tham chiếu bởi template_uuid. Chỉ được phép cùng với template_uuid.

batch-send-transactional-email

Gửi một loạt email giao dịch trong một lệnh gọi API Mailtrap (luồng gửi mặc định). Các trường dùng chung nằm trong base; các ghi đè theo từng người nhận nằm trong requests[]. Mỗi yêu cầu phải bao gồm ít nhất một người nhận qua to, cc hoặc bcc. Cùng quy tắc loại trừ lẫn nhau giữa nội tuyến và mẫu như send-email — được kiểm tra sau khi hợp nhất cơ sở với từng yêu cầu.

Tham số:

  • base (tùy chọn): Đối tượng chứa các trường dùng chung cho cả loạt.
    • from (tùy chọn): Người gửi dưới dạng { email, name? } (chuỗi email trần cũng được chấp nhận khi chạy). Dự phòng về DEFAULT_FROM_EMAIL.
    • reply_to (tùy chọn): Địa chỉ trả lời (reply-to).
    • subject / text / html / category (tùy chọn, chế độ nội tuyến): Nội dung mặc định cho mọi yêu cầu.
    • template_uuid / template_variables (tùy chọn, chế độ mẫu): Mẫu mặc định + biến. Loại trừ lẫn nhau với các trường nội tuyến.
    • custom_variables (tùy chọn): Biến tùy chỉnh mặc định (giá trị chuỗi).
    • headers (tùy chọn): Tiêu đề tùy chỉnh mặc định.
  • requests (bắt buộc): Mảng không rỗng các thông điệp theo từng người nhận. Mỗi mục có:
    • to (tùy chọn): Mảng người nhận dưới dạng đối tượng { email, name? } (chuỗi email trần hoặc một địa chỉ không phải mảng cũng được chấp nhận khi chạy). Tùy chọn nếu cc hoặc bcc được cung cấp; ít nhất một trong số to / cc / bcc phải chứa người nhận.
    • cc, bcc, reply_to (tùy chọn).
    • Ghi đè nội tuyến (subject/text/html/category) hoặc mẫu (template_uuid/template_variables); trường nào bị bỏ qua sẽ dự phòng về giá trị base tương ứng.
    • custom_variables, headers (tùy chọn).

batch-send-bulk-email

Gửi một loạt email hàng loạt qua API bulk-stream của Mailtrap. Cùng cấu trúc base + requests[], quy tắc xác thực và quy tắc nội tuyến-vs-mẫu như batch-send-transactional-email — điểm khác biệt duy nhất là công cụ này định tuyến lệnh gọi qua endpoint bulk thay vì endpoint giao dịch. Xem các tham số ở trên.

list-email-logs

Liệt kê nhật ký email đã gửi (lịch sử gửi thư) với phân trang và bộ lọc tùy chọn. Dùng để gỡ lỗi các vấn đề gửi thư từ IDE.

Tham số:

  • search_after (tùy chọn): Con trỏ phân trang từ next_page_cursor của phản hồi trước đó
  • sent_after (tùy chọn): Ngày/giờ ISO 8601; chỉ nhật ký gửi sau thời điểm này
  • sent_before (tùy chọn): Ngày/giờ ISO 8601; chỉ nhật ký gửi trước thời điểm này
  • from_email (tùy chọn): Lọc theo email người gửi; dùng với from_operator (mặc định: ci_equal)
  • to_email (tùy chọn): Lọc theo email người nhận; dùng với to_operator (mặc định: ci_equal)
  • status (tùy chọn): Lọc theo trạng thái gửi: delivered, not_delivered, enqueued, opted_out; dùng với status_operator (mặc định: equal)
  • subject (tùy chọn): Lọc theo tiêu đề email; dùng với subject_operator (mặc định: ci_contain). Dùng subject_operator: empty/not_empty để lọc theo sự hiện diện của tiêu đề.
  • sending_domain_id (tùy chọn): Lọc theo ID tên miền gửi thư (số); dùng với sending_domain_id_operator (mặc định: equal)
  • sending_stream (tùy chọn): Lọc theo luồng: transactional hoặc bulk; dùng với sending_stream_operator (mặc định: equal)
  • events (tùy chọn): Lọc theo (các) loại sự kiện: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; dùng với events_operator (include_event / not_include_event)
  • clicks_count / opens_count (tùy chọn): Lọc theo số lần nhấp/mở; dùng với *_operator: equal, greater_than, less_than
  • client_ip / sending_ip (tùy chọn): Lọc theo IP; dùng với *_operator: equal, not_equal, contain, not_contain
  • email_service_provider_response (tùy chọn): Lọc theo văn bản phản hồi của nhà cung cấp; dùng với *_operator (ci_contain, v.v.)
  • email_service_provider (tùy chọn): Lọc theo nhà cung cấp (chính xác); dùng với *_operator: equal, not_equal
  • recipient_mx (tùy chọn): Lọc theo MX của người nhận; dùng với recipient_mx_operator (ci_contain, v.v.)
  • category (tùy chọn): Lọc theo danh mục email; dùng với category_operator: equal, not_equal

Tất cả các tham số đều tùy chọn.

get-email-log-message

Lấy một thông điệp nhật ký email theo ID (UUID): bản tóm tắt dễ đọc (từ, đến, tiêu đề, thời gian gửi, trạng thái, danh mục, luồng, mức độ tương tác, ngữ cảnh gửi), sau đó là lịch sử sự kiện chi tiết. Tùy chọn, với include_content: true, bạn cũng có thể tải và hiển thị nội dung thông điệp (HTML và văn bản thuần) khi Mailtrap cung cấp URL thông điệp thô.

Tham số:

  • message_id (bắt buộc): UUID của thông điệp nhật ký email (từ phản hồi gửi hoặc danh sách nhật ký email). Dùng list-email-logs để tìm ID thông điệp.
  • include_content (tùy chọn): Khi true, lấy EML thô (nếu raw_message_url có sẵn) và nối thêm các phần nội dung HTML và văn bản thuần đã phân tích, tương tự như show-sandbox-email-message.

get-sending-stats

Nhận số liệu thống kê gửi email (tỷ lệ gửi thành công, trả lại, mở, nhấp chuột, spam) cho một khoảng thời gian. Tùy chọn phân nhóm theo miền, danh mục, nhà cung cấp dịch vụ email hoặc ngày. Kiểm tra tỷ lệ gửi thành công mà không cần rời khỏi trình soạn thảo.

Tham số:

  • start_date (bắt buộc): Ngày bắt đầu cho khoảng thời gian thống kê (YYYY-MM-DD)
  • end_date (bắt buộc): Ngày kết thúc cho khoảng thời gian thống kê (YYYY-MM-DD)
  • breakdown (tùy chọn): Cách phân nhóm số liệu: aggregated (mặc định), by_domain, by_category, by_email_service_provider hoặc by_date
  • sending_domain_ids (tùy chọn): Giới hạn kết quả theo các ID miền gửi này (mảng số nguyên)
  • sending_streams (tùy chọn): Giới hạn theo transactional và/hoặc bulk (mảng chuỗi)
  • categories (tùy chọn): Giới hạn theo các danh mục email này (mảng chuỗi)
  • email_service_providers (tùy chọn): Giới hạn theo các nhà cung cấp này, ví dụ: Google, Yahoo, Outlook (mảng chuỗi)

create-template

Tạo một mẫu email mới trong tài khoản Mailtrap của bạn.

Tham số:

  • name (bắt buộc): Tên của mẫu
  • subject (bắt buộc): Dòng chủ đề email
  • html (hoặc text là bắt buộc): Nội dung HTML của mẫu
  • text (hoặc html là bắt buộc): Phiên bản văn bản thuần của mẫu
  • category (tùy chọn): Danh mục mẫu (mặc định là "General")

list-templates

Liệt kê tất cả các mẫu email trong tài khoản Mailtrap của bạn.

Tham số:

  • Không yêu cầu tham số

get-template

Lấy một mẫu email theo ID, bao gồm chủ đề, danh mục và nội dung HTML/văn bản.

Tham số:

  • template_id (bắt buộc): ID của mẫu cần lấy

update-template

Cập nhật một mẫu email hiện có.

Tham số:

  • template_id (bắt buộc): ID của mẫu cần cập nhật
  • name (tùy chọn): Tên mới cho mẫu
  • subject (tùy chọn): Dòng chủ đề email mới
  • html (tùy chọn): Nội dung HTML mới của mẫu
  • text (tùy chọn): Phiên bản văn bản thuần mới của mẫu
  • category (tùy chọn): Danh mục mới cho mẫu

[!NOTE] Phải cung cấp ít nhất một trường có thể cập nhật (tên, chủ đề, html, văn bản hoặc danh mục) khi gọi update-template để thực hiện cập nhật.

delete-template

Xóa một mẫu email hiện có.

Tham số:

  • template_id (bắt buộc): ID của mẫu cần xóa

send-sandbox-email

Gửi email đến hộp thư kiểm thử Mailtrap của bạn cho mục đích phát triển và kiểm thử. Điều này rất phù hợp để kiểm thử các mẫu email mà không cần gửi email đến người nhận thực. Hỗ trợ hai chế độ giống như send-email — nội dung trực tiếp (inline) hoặc dựa trên mẫu (template_uuid).

Tham số:

  • test_inbox_id (tùy chọn): ID hộp thư kiểm thử Mailtrap. Bắt buộc trừ khi MAILTRAP_TEST_INBOX_ID được đặt; truyền mỗi lần gọi để nhắm đến một hộp thư cụ thể.
  • from (tùy chọn): Người gửi dưới dạng { email, name? } (một chuỗi email trần cũng được chấp nhận khi chạy). Nếu không cung cấp, DEFAULT_FROM_EMAIL sẽ được sử dụng.
  • to (tùy chọn): Mảng người nhận dưới dạng các đối tượng { email, name? } (chuỗi email trần trong mảng, hoặc chuỗi email thường phân tách bằng dấu phẩy, cũng được chấp nhận khi chạy). Tùy chọn nếu cc hoặc bcc được cung cấp; ít nhất một trong số to / cc / bcc phải chứa người nhận.
  • cc (tùy chọn): Mảng người nhận CC dưới dạng các đối tượng { email, name? } (chuỗi email trần cũng được chấp nhận khi chạy).
  • bcc (tùy chọn): Mảng người nhận BCC dưới dạng các đối tượng { email, name? } (chuỗi email trần cũng được chấp nhận khi chạy).
  • subject (có điều kiện): Dòng chủ đề email. Bắt buộc đối với gửi trực tiếp (inline); phải bỏ qua khi template_uuid được đặt.
  • text (có điều kiện): Nội dung văn bản email. Bắt buộc (cùng với hoặc thay cho html) đối với gửi trực tiếp; phải bỏ qua khi template_uuid được đặt.
  • html (có điều kiện): Phiên bản HTML của nội dung email. Bắt buộc (cùng với hoặc thay cho text) đối với gửi trực tiếp; phải bỏ qua khi template_uuid được đặt.
  • category (tùy chọn): Danh mục email để theo dõi. Phải bỏ qua khi template_uuid được đặt.
  • template_uuid (tùy chọn): Sử dụng mẫu email Mailtrap thay vì nội dung trực tiếp. Khi được đặt, subject / text / html / category phải được bỏ qua.
  • template_variables (tùy chọn): Đối tượng các biến được thay thế vào mẫu được tham chiếu bởi template_uuid. Chỉ được phép đi kèm với template_uuid.

batch-send-sandbox-email

Gửi một loạt email đến hộp thư kiểm thử Mailtrap của bạn trong một lần gọi API, mà không gửi đến người nhận thực. Cùng dạng base + requests[], xác thực và quy tắc nội dung-trực-tiếp-vs-mẫu như batch-send-transactional-email — điểm khác biệt là công cụ này định tuyến lệnh gọi qua điểm cuối sandbox cho một hộp thư kiểm thử duy nhất.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox (hộp thư kiểm thử) Mailtrap. Bắt buộc trừ khi MAILTRAP_SANDBOX_ID được đặt; truyền mỗi lần gọi để nhắm đến một sandbox cụ thể.
  • base (tùy chọn), requests (bắt buộc): Xem batch-send-transactional-email ở trên.

[!NOTE] Đối với các công cụ sandbox, hãy cung cấp test_inbox_id trong lệnh gọi công cụ hoặc đặt biến môi trường MAILTRAP_TEST_INBOX_ID. Bạn có thể chuyển đổi giữa các hộp thư trong mỗi lần gọi bằng cách truyền test_inbox_id. Các công cụ nhận sandbox_id sử dụng MAILTRAP_SANDBOX_ID trước tiên.

get-sandbox-messages

Truy xuất danh sách các thông điệp từ hộp thư kiểm thử Mailtrap của bạn. Hữu ích để kiểm tra những email đã được nhận trong sandbox của bạn trong quá trình kiểm thử.

Tham số:

  • page (tùy chọn): Số trang cho phân trang (tối thiểu: 1)
  • last_id (tùy chọn): Phân trang sử dụng ID thông điệp cuối cùng. Trả về các thông điệp sau ID thông điệp đã chỉ định (tối thiểu: 1)
  • search (tùy chọn): Truy vấn tìm kiếm để lọc thông điệp

[!NOTE] Tất cả các tham số đều tùy chọn. Nếu không có tham số nào được cung cấp, trang đầu tiên của các thông điệp từ hộp thư sẽ được trả về. Sử dụng page cho phân trang truyền thống, last_id cho phân trang dựa trên con trỏ, hoặc search để lọc thông điệp theo nội dung.

show-sandbox-email-message

Hiển thị thông tin chi tiết và nội dung của một thông điệp email cụ thể từ hộp thư kiểm thử Mailtrap của bạn, bao gồm nội dung thân HTML và văn bản.

Tham số:

  • message_id (bắt buộc): ID của thông điệp email sandbox cần truy xuất

[!NOTE] Sử dụng get-sandbox-messages trước để lấy danh sách các thông điệp và ID của chúng, sau đó sử dụng công cụ này để xem nội dung đầy đủ của một thông điệp cụ thể.

get-sandbox-project

Lấy một dự án sandbox theo ID, bao gồm các hộp thư và số lượng email của dự án.

Tham số:

  • project_id (bắt buộc): ID của dự án cần lấy

update-sandbox-project

Đổi tên một dự án sandbox hiện có.

Tham số:

  • project_id (bắt buộc): ID của dự án cần cập nhật
  • name (bắt buộc): Tên mới cho dự án (2–100 ký tự)

list-sandboxes

Liệt kê mọi sandbox mà mã API token có thể truy cập trên tất cả các dự án.

Tham số:

  • Không yêu cầu tham số

mark-sandbox-as-read

Đánh dấu tất cả các thông điệp trong một sandbox là đã đọc.

Tham số:

  • sandbox_id (bắt buộc): ID của sandbox cần thao tác

reset-sandbox-credentials

Đặt lại thông tin xác thực SMTP cho một sandbox. Trả về tên người dùng/mật khẩu mới.

Tham số:

  • sandbox_id (bắt buộc): ID của sandbox cần thao tác

enable-sandbox-email-address

Bật địa chỉ nhận-email cho một sandbox (bật địa chỉ Mailtrap chuyển các thông điệp đến sandbox qua SMTP).

Tham số:

  • sandbox_id (bắt buộc): ID của sandbox cần thao tác

reset-sandbox-email-address

Tạo một địa chỉ nhận-email mới cho một sandbox.

Tham số:

  • sandbox_id (bắt buộc): ID của sandbox cần thao tác

forward-sandbox-message

Chuyển tiếp một thông điệp sandbox đến một địa chỉ email bên ngoài. Sẽ tính vào hạn mức chuyển tiếp hàng tháng của bạn.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox cần chuyển tiếp
  • email (bắt buộc): Địa chỉ email để chuyển tiếp thông điệp đến

update-sandbox-message

Đánh dấu một thông điệp sandbox là đã đọc hoặc chưa đọc.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox cần cập nhật
  • is_read (bắt buộc): true đánh dấu là đã đọc, false đánh dấu là chưa đọc

delete-sandbox-message

Xóa một thông điệp sandbox đơn lẻ.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox cần xóa

get-sandbox-message-spam-score

Lấy báo cáo spam SpamAssassin cho một thông điệp sandbox (điểm, quy tắc, báo cáo đầy đủ). Thay thế độc lập cho include_spam_report: true trên show-sandbox-email-message.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-html-analysis

Lấy báo cáo phân tích HTML cho một thông điệp sandbox (điểm tương thích máy khách, các phần tử có vấn đề). Thay thế độc lập cho include_html_analysis: true trên show-sandbox-email-message.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-headers

Lấy các tiêu đề thư đã phân tích cho một thông điệp sandbox.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-html

Lấy nội dung thân HTML đã kết xuất của một thông điệp sandbox.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-text

Lấy nội dung thân văn bản thuần của một thông điệp sandbox.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-raw

Lấy thông điệp thô, có định dạng MIME (tiêu đề + thân) cho một thông điệp sandbox.

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-eml

Lấy thông điệp được kết xuất dưới dạng tải trọng tệp EML (phù hợp để đính kèm vào vé hỗ trợ hoặc nhập vào một máy khách email khác).

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-message-html-source

Lấy mã nguồn HTML chưa kết xuất của một thông điệp sandbox (HTML trước khi có bất kỳ biến đổi nào từ phía Mailtrap như viết lại liên kết CID).

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

list-sandbox-attachments

Liệt kê tất cả các tệp đính kèm trên một thông điệp sandbox (tên tệp, loại nội dung, kích thước, đường dẫn tải xuống).

Tham số:

  • sandbox_id (tùy chọn): ID sandbox. Dự phòng trở lại MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của thông điệp sandbox

get-sandbox-attachment

Lấy siêu dữ liệu và URL tải xuống cho một tệp đính kèm đơn lẻ.

Tham số:

  • sandbox_id (tùy chọn): ID Sandbox. Dự phòng sang MAILTRAP_SANDBOX_ID.
  • message_id (bắt buộc): ID của tin nhắn sandbox chứa tệp đính kèm
  • attachment_id (bắt buộc): ID của tệp đính kèm cần lấy

list-sending-domains

Liệt kê các miền gửi và trạng thái xác minh DNS của chúng.

Tham số:

  • Không yêu cầu tham số

get-sending-domain

Lấy thông tin miền gửi theo ID và trạng thái xác minh của nó (bao gồm cả bản ghi DNS). Tùy chọn bao gồm hướng dẫn thiết lập DNS bằng cách đặt include_setup_instructions thành true.

Tham số:

  • sending_domain_id (bắt buộc): ID miền gửi
  • include_setup_instructions (tùy chọn): Nếu true, nối hướng dẫn thiết lập DNS vào phản hồi. Mặc định: false

create-sending-domain

Tạo một miền gửi mới. Sau khi tạo, hãy thêm bản ghi DNS để xác minh miền (dùng get-sending-domain với include_setup_instructions: true để xem các bản ghi).

Tham số:

  • domain_name (bắt buộc): Tên miền (ví dụ: example.com)

delete-sending-domain

Xóa một miền gửi.

Tham số:

  • sending_domain_id (bắt buộc): ID miền gửi cần xóa

send-sending-domain-setup-instructions

Gửi hướng dẫn thiết lập DNS cho một miền gửi đến một địa chỉ nhất định. Hữu ích khi cần chuyển tiếp bản ghi DNS cho đồng nghiệp DevOps.

Tham số:

  • sending_domain_id (bắt buộc): ID miền gửi
  • email (bắt buộc): Địa chỉ email để gửi hướng dẫn thiết lập DNS đến

list-suppressions

Liệt kê hoặc tìm kiếm các địa chỉ bị chặn (hard bounce, khiếu nại spam, hủy đăng ký, nhập thủ công). Trả về tối đa 1000 kết quả mỗi lần gọi.

Tham số:

  • email (tùy chọn): Bộ lọc email. Chỉ trả về các địa chỉ bị chặn khớp với địa chỉ này.

delete-suppression

Xóa một địa chỉ bị chặn theo ID. Mailtrap sẽ tiếp tục gửi thư đến email này trừ khi nó bị chặn lại.

Tham số:

  • suppression_id (bắt buộc): ID của địa chỉ bị chặn cần xóa

list-webhooks

Liệt kê tất cả webhook được cấu hình cho tài khoản. Trả về toàn bộ bản ghi webhook dưới dạng JSON.

Tham số:

  • Không yêu cầu tham số

get-webhook

Lấy một webhook theo ID. Trả về toàn bộ bản ghi webhook dưới dạng JSON. Lưu ý: signing_secret không được trả về ở đây — nó chỉ có trong phản hồi từ create-webhook.

Tham số:

  • webhook_id (bắt buộc): ID của webhook cần lấy

create-webhook

Tạo một webhook. Phản hồi bao gồm signing_secret để xác minh chữ ký payload webhook — bí mật này chỉ được trả về một lần khi tạo, vì vậy hãy lưu trữ ngay. Nếu bạn làm mất nó, hãy tạo lại webhook.

Tham số:

  • url (bắt buộc): URL mà Mailtrap sẽ POST các sự kiện webhook đến
  • webhook_type (bắt buộc): "email_sending", "audit_log", hoặc "inbound_receiving"
  • active (tùy chọn, boolean): mặc định là true
  • payload_format (tùy chọn): "json" hoặc "jsonlines". Mặc định là "json"
  • sending_stream (tùy chọn, chỉ dành cho email_sending): "transactional" hoặc "bulk"
  • event_types (tùy chọn, chỉ dành cho email_sending): mảng gồm delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (tùy chọn, chỉ dành cho email_sending): ID miền gửi để giới hạn phạm vi webhook này
  • inbound_inbox_id (tùy chọn, chỉ dành cho inbound_receiving): ID của hộp thư đến inbound mà webhook được liên kết; bỏ qua để áp dụng cho tất cả hộp thư đến trong tài khoản

update-webhook

Cập nhật các trường có thể thay đổi của webhook. webhook_type, sending_stream, và domain_id không thể thay đổi sau khi tạo — hãy tạo lại webhook nếu bạn cần thay đổi các trường đó.

Tham số:

  • webhook_id (bắt buộc): ID của webhook cần cập nhật
  • url (tùy chọn): URL webhook mới
  • active (tùy chọn, boolean): Bật hoặc tắt webhook
  • payload_format (tùy chọn): "json" hoặc "jsonlines"
  • event_types (tùy chọn, chỉ dành cho email_sending): mảng gồm delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • inbound_inbox_id (tùy chọn, chỉ dành cho inbound_receiving): ID của hộp thư đến inbound mà webhook được liên kết

delete-webhook

Xóa vĩnh viễn một webhook theo ID. Trả về bản ghi webhook đã xóa.

Tham số:

  • webhook_id (bắt buộc): ID của webhook cần xóa

get-contact

Lấy thông tin liên hệ theo ID hoặc email. Trả về toàn bộ bản ghi liên hệ (tư cách thành viên danh sách, trạng thái, trường tùy chỉnh).

Tham số:

  • contact_identifier (bắt buộc): ID liên hệ hoặc địa chỉ email

create-contact

Tạo một liên hệ mới.

Tham số:

  • email (bắt buộc): Địa chỉ email
  • fields (tùy chọn): Giá trị trường tùy chỉnh theo khóa merge tag (ví dụ: first_name). Giá trị chuỗi, số hoặc boolean
  • list_ids (tùy chọn): ID của các danh sách liên hệ để đăng ký liên hệ này
  • unsubscribed (tùy chọn, boolean): Tạo liên hệ ở trạng thái unsubscribed

update-contact

Cập nhật một liên hệ hiện có được xác định theo ID hoặc email. list_ids thay thế toàn bộ tập hợp tư cách thành viên của liên hệ; list_ids_included/list_ids_excluded thêm/xóa mà không ảnh hưởng đến phần còn lại.

Tham số:

  • contact_identifier (bắt buộc): ID liên hệ hoặc email
  • email (tùy chọn): Địa chỉ email mới
  • fields (tùy chọn): Giá trị trường tùy chỉnh theo khóa merge tag
  • list_ids (tùy chọn): Thay thế tập hợp tư cách thành viên bằng danh sách chính xác này
  • list_ids_included (tùy chọn): ID danh sách để thêm (cộng dồn)
  • list_ids_excluded (tùy chọn): ID danh sách để xóa
  • unsubscribed (tùy chọn, boolean): Đặt thành unsubscribed (true) hoặc subscribed (false)

delete-contact

Xóa vĩnh viễn một liên hệ theo ID hoặc email. Trả về bản ghi liên hệ đã xóa khi API phản hồi kèm bản ghi đó; nếu không, trả về payload xác nhận.

Tham số:

  • contact_identifier (bắt buộc): ID liên hệ hoặc email

create-contact-event

Ghi lại một sự kiện liên hệ cho một liên hệ (theo ID hoặc email). Được dùng để kích hoạt các quy trình tự động hóa danh sách liên hệ.

Tham số:

  • contact_identifier (bắt buộc): ID liên hệ hoặc email
  • name (bắt buộc): Tên sự kiện (khớp với trình kích hoạt tự động hóa)
  • params (bắt buộc): Đối tượng chứa các cặp khóa/giá trị tùy ý. Giá trị có thể là chuỗi, số, boolean hoặc null

list-contact-lists

Liệt kê tất cả danh sách liên hệ của tài khoản.

Tham số:

  • search (tùy chọn): Lọc danh sách liên hệ theo tên (khớp không phân biệt hoa thường), ví dụ: news

get-contact-list

Lấy một danh sách liên hệ theo ID.

Tham số:

  • list_id (bắt buộc): ID của danh sách liên hệ cần lấy

create-contact-list

Tạo một danh sách liên hệ mới.

Tham số:

  • name (bắt buộc): Tên cho danh sách mới

update-contact-list

Đổi tên một danh sách liên hệ hiện có.

Tham số:

  • list_id (bắt buộc): ID của danh sách liên hệ
  • name (bắt buộc): Tên mới cho danh sách

delete-contact-list

Xóa vĩnh viễn một danh sách liên hệ theo ID.

Tham số:

  • list_id (bắt buộc): ID của danh sách liên hệ cần xóa

list-contact-fields

Liệt kê tất cả định nghĩa trường liên hệ của tài khoản.

Tham số:

  • Không yêu cầu tham số

get-contact-field

Lấy định nghĩa trường liên hệ theo ID.

Tham số:

  • field_id (bắt buộc): ID của trường liên hệ

create-contact-field

Tạo một định nghĩa trường liên hệ mới. merge_tag phải là duy nhất trong tài khoản và được dùng làm tên placeholder trong các biến mẫu.

Tham số:

  • name (bắt buộc): Tên hiển thị (ví dụ: "First Name")
  • merge_tag (bắt buộc): Tên placeholder duy nhất (ví dụ: first_name)
  • data_type (bắt buộc): Một trong các giá trị text, number, boolean, date

update-contact-field

Cập nhật một định nghĩa trường liên hệ. Có thể thay đổi bất kỳ tổ hợp nào của name, merge_tag, và data_type.

Tham số:

  • field_id (bắt buộc): ID của trường liên hệ
  • name (tùy chọn): Tên hiển thị mới
  • merge_tag (tùy chọn): Merge tag mới (phải giữ tính duy nhất)
  • data_type (tùy chọn): Một trong các giá trị text, number, boolean, date

delete-contact-field

Xóa vĩnh viễn một định nghĩa trường liên hệ theo ID.

Tham số:

  • field_id (bắt buộc): ID của trường liên hệ cần xóa

create-contact-import

Nhập hàng loạt liên hệ. Trả về bản ghi công việc nhập; kiểm tra trạng thái của nó bằng get-contact-import.

Tham số:

  • contacts (bắt buộc): Mảng các mục liên hệ. Mỗi mục cần có:
    • email (bắt buộc): Địa chỉ email liên hệ
    • fields (tùy chọn): Giá trị trường tùy chỉnh theo khóa merge tag (giá trị chuỗi hoặc số)
    • list_ids_included (tùy chọn): ID danh sách để thêm liên hệ vào
    • list_ids_excluded (tùy chọn): ID danh sách để xóa liên hệ khỏi

get-contact-import

Lấy trạng thái của một công việc nhập liên hệ (created/started/finished/failed) kèm số lượng created/updated/over-limit.

Tham số:

  • import_id (bắt buộc): ID của công việc nhập liên hệ

create-contact-export

Xuất các liên hệ khớp với một tập hợp các bộ lọc kết hợp bằng AND. Trả về bản ghi công việc xuất; kiểm tra trạng thái bằng get-contact-export để lấy URL tải xuống khi status là finished.

Tham số:

  • filters (bắt buộc): Mảng các đối tượng bộ lọc. Mỗi bộ lọc có:
    • name (bắt buộc): Trường để lọc (list_id, subscription_status, email, v.v.)
    • operator (bắt buộc): Một trong các giá trị equal, not_equal, contains, not_contains, is_empty, is_not_empty
    • value (bắt buộc): Giá trị so sánh (chuỗi, số, boolean hoặc mảng)

get-contact-export

Lấy trạng thái của một công việc xuất liên hệ. Khi status là finished, trường url chứa liên kết tải xuống CSV.

Tham số:

  • export_id (bắt buộc): ID của công việc xuất liên hệ

list-accounts

Liệt kê các tài khoản Mailtrap mà token API hiện tại có thể truy cập, kèm mức quyền truy cập của từng tài khoản.

Tham số:

  • Không yêu cầu tham số

get-billing-usage

Lấy mức sử dụng chu kỳ thanh toán hiện tại của tài khoản: gói gửi và gói kiểm thử, giới hạn và số lượng hiện tại.

Tham số:

  • Không yêu cầu tham số

list-account-accesses

Liệt kê các quyền truy cập tài khoản (người dùng, lời mời, token API) của tài khoản. Các bộ lọc tùy chọn thu hẹp kết quả theo các tài nguyên cụ thể. Yêu cầu quyền quản trị viên/chủ sở hữu tài khoản.

Tham số:

  • domain_uuids (tùy chọn): Lọc theo UUID miền gửi (mảng chuỗi)
  • inbox_ids (tùy chọn): Lọc theo ID hộp thư đến sandbox (mảng chuỗi)
  • project_ids (tùy chọn): Lọc theo ID dự án sandbox (mảng chuỗi)

remove-account-access

Xóa một quyền truy cập tài khoản theo ID. Đối với bộ xác định User, thao tác này thu hồi quyền của họ; đối với bộ xác định Invite hoặc ApiToken, thao tác này xóa hoàn toàn bộ xác định đó. Yêu cầu quyền quản trị viên/chủ sở hữu.

Tham số:

  • account_access_id (bắt buộc): ID của bản ghi quyền truy cập cần xóa

get-permission-resources

Lấy tất cả tài nguyên (hộp thư đến, dự án, miền, thanh toán, tài khoản) mà token API có quyền quản trị, được phân cấp theo thứ bậc.

Tham số:

  • Không yêu cầu tham số

bulk-update-permissions

Tạo, cập nhật hoặc xóa hàng loạt quyền cho một quyền truy cập tài khoản duy nhất. Các cặp (resource_type, resource_id) hiện có sẽ được cập nhật; các cặp mới sẽ được tạo. Đặt destroy: true trên một mục để xóa mục đó.

Tham số:

  • account_access_id (bắt buộc): ID truy cập tài khoản đích
  • permissions (bắt buộc): Mảng các mục quyền. Mỗi mục có:
    • resource_id (bắt buộc): ID tài nguyên (số hoặc chuỗi)
    • resource_type (bắt buộc): Một trong các giá trị account, project, inbox, domain, billing
    • access_level (tùy chọn): admin/100 hoặc viewer/10
    • destroy (tùy chọn, boolean): Khi true, xóa quyền này thay vì tạo/cập nhật

list-api-tokens

Liệt kê tất cả API token của tài khoản.

Tham số:

  • Không yêu cầu tham số

create-api-token

Tạo một API token mới. Phản hồi bao gồm giá trị bí mật token — đây là lần duy nhất token đầy đủ được trả về, vì vậy hãy lưu trữ ngay lập tức. Nếu bạn làm mất nó, hãy tạo lại token.

Tham số:

  • name (bắt buộc): Tên hiển thị cho token
  • resources (tùy chọn): Mảng các quyền tài nguyên để giới hạn phạm vi token. Mỗi mục có:
    • resource_type (bắt buộc): Một trong các giá trị account, project, inbox, domain, billing
    • resource_id (bắt buộc): ID của tài nguyên
    • access_level (bắt buộc): 100 (quản trị) hoặc 10 (người xem)

get-api-token

Lấy một API token theo ID. Chỉ trả về siêu dữ liệu — giá trị token bí mật không được trả về ở đây (chỉ từ create-api-token / reset-api-token).

Tham số:

  • api_token_id (bắt buộc): ID của API token

reset-api-token

Đặt lại (xoay vòng) một API token theo ID. Phản hồi bao gồm giá trị bí mật token mới — chỉ được trả về trong lần gọi này, vì vậy hãy lưu trữ ngay lập tức. Token trước đó sẽ bị vô hiệu hóa.

Tham số:

  • api_token_id (bắt buộc): ID của API token cần đặt lại

delete-api-token

Xóa vĩnh viễn một API token theo ID. Token không thể xác thực được nữa sau khi xóa.

Tham số:

  • api_token_id (bắt buộc): ID của API token cần xóa

list-sub-accounts

Liệt kê các tài khoản con trong tổ chức. Yêu cầu biến môi trường MAILTRAP_ORGANIZATION_ID và quyền quản lý tài khoản con.

Tham số:

  • Không yêu cầu tham số

create-sub-account

Tạo một tài khoản con mới trong tổ chức. Yêu cầu biến môi trường MAILTRAP_ORGANIZATION_ID và quyền quản lý tài khoản con.

Tham số:

  • name (bắt buộc): Tên hiển thị cho tài khoản con mới

list-inbound-folders

Liệt kê tất cả thư mục inbound trong tài khoản. Trả về bản tóm tắt đã định dạng.

Tham số:

  • Không yêu cầu tham số

get-inbound-folder

Lấy một thư mục inbound theo ID. Trả về bản ghi đầy đủ của thư mục dưới dạng JSON.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound

create-inbound-folder

Tạo một thư mục inbound mới.

Tham số:

  • name (bắt buộc): Tên thư mục

update-inbound-folder

Đổi tên một thư mục inbound.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound
  • name (bắt buộc): Tên mới của thư mục

delete-inbound-folder

Xóa vĩnh viễn một thư mục inbound cùng với tất cả hộp thư bên trong.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound

list-inbound-inboxes

Liệt kê tất cả hộp thư trong một thư mục inbound. Trả về bản tóm tắt đã định dạng.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound

get-inbound-inbox

Lấy một hộp thư inbound theo ID. Trả về bản ghi đầy đủ của hộp thư dưới dạng JSON.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound
  • inbox_id (bắt buộc): ID của hộp thư

create-inbound-inbox

Tạo một hộp thư inbound mới trong một thư mục.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound
  • name (bắt buộc): Tên hộp thư
  • domain_id (tùy chọn): Gắn vào một miền gửi tùy chỉnh (hộp thư catch-all). Bỏ trống để dùng hộp thư do Mailtrap lưu trữ

update-inbound-inbox

Đổi tên một hộp thư inbound.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound
  • inbox_id (bắt buộc): ID của hộp thư
  • name (bắt buộc): Tên mới của hộp thư

delete-inbound-inbox

Xóa vĩnh viễn một hộp thư inbound.

Tham số:

  • folder_id (bắt buộc): ID của thư mục inbound
  • inbox_id (bắt buộc): ID của hộp thư

list-inbound-messages

Liệt kê các tin nhắn đã nhận trong một hộp thư inbound (phân trang bằng con trỏ). Trả về bản tóm tắt đã định dạng kèm gợi ý trang tiếp theo khi còn kết quả.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • last_id (tùy chọn): Con trỏ phân trang từ last_id của phản hồi trước đó

get-inbound-message

Lấy một tin nhắn inbound với toàn bộ nội dung và URL tải tệp đính kèm. Trả về bản ghi đầy đủ của tin nhắn dưới dạng JSON.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • message_id (bắt buộc): ID của tin nhắn

delete-inbound-message

Xóa vĩnh viễn một tin nhắn inbound.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • message_id (bắt buộc): ID của tin nhắn

reply-to-inbound-message

Trả lời một tin nhắn inbound (gửi đến người gửi ban đầu). Gửi một email thực. Địa chỉ chấp nhận chuỗi email đơn thuần hoặc { email, name? }.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • message_id (bắt buộc): ID của tin nhắn cần trả lời
  • text / html (ít nhất một trường được khuyến nghị): Nội dung trả lời
  • from (tùy chọn): Người gửi. Bị từ chối đối với hộp thư do Mailtrap lưu trữ; bắt buộc đối với hộp thư dùng miền tùy chỉnh
  • cc / bcc / reply_to (tùy chọn): Các địa chỉ bổ sung
  • category (tùy chọn): Danh mục tin nhắn
  • attachments (tùy chọn): Mảng các giá trị { content (base64), filename, type?, disposition?, content_id? }
  • headers / custom_variables (tùy chọn): Các đối tượng chứa giá trị chuỗi

reply-all-to-inbound-message

Trả lời một tin nhắn inbound và sao chép các người nhận khác của tin gốc. Gửi một email thực. Tham số tương tự như reply-to-inbound-message.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • message_id (bắt buộc): ID của tin nhắn cần trả lời
  • Cộng với các trường gửi tùy chọn tương tự như reply-to-inbound-message

forward-inbound-message

Chuyển tiếp một tin nhắn inbound đến người nhận mới. Gửi một email thực.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • message_id (bắt buộc): ID của tin nhắn cần chuyển tiếp
  • to (bắt buộc): Ít nhất một người nhận (chuỗi email đơn thuần hoặc { email, name? }, hoặc một mảng)
  • Cộng với các trường gửi tùy chọn tương tự như reply-to-inbound-message

list-inbound-threads

Liệt kê các chuỗi hội thoại trong một hộp thư inbound (phân trang bằng con trỏ). Trả về bản tóm tắt đã định dạng kèm gợi ý trang tiếp theo khi còn kết quả.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • last_id (tùy chọn): Con trỏ phân trang từ last_id của phản hồi trước đó

get-inbound-thread

Lấy một chuỗi hội thoại inbound với các tin nhắn được nhúng kèm (cũ nhất trước). Trả về bản ghi đầy đủ của chuỗi dưới dạng JSON.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • thread_id (bắt buộc): ID của chuỗi hội thoại

delete-inbound-thread

Xóa vĩnh viễn một chuỗi hội thoại inbound.

Tham số:

  • inbox_id (bắt buộc): ID của hộp thư
  • thread_id (bắt buộc): ID của chuỗi hội thoại

Phát triển

  1. Sao chép kho lưu trữ:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Cài đặt các phụ thuộc:
npm install

Cấu hình với Claude Desktop hoặc Cursor

[!TIP] Xem vị trí của tệp cấu hình trong phần Setup.

Thêm cấu hình sau:

{
  "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"
      }
    }
  }
}

Nếu bạn dùng asdf để quản lý Node.js, hãy dùng đường dẫn tuyệt đối đến tệp thực thi:

(ví dụ cho 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] Xem vị trí của tệp cấu hình trong phần 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"
        }
      }
    }
  }
}

Kiểm thử

Chạy công cụ với Mailtrap thực

Có hai cách để chạy thử một công cụ từ đầu đến cuối với tài khoản Mailtrap thực: giao diện trình duyệt MCP Inspector để khám phá tương tác, hoặc chế độ CLI của nó để gọi một lần từ shell.

Cả hai cách đều yêu cầu bundle phải được xây dựng trước:

npm run build

và MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID phải được xuất trong shell của bạn (script mcp:cli sẽ chuyển tiếp cả hai đến server đã khởi chạy).

Giao diện trình duyệt

npm run dev

Inspector in ra một URL như http://localhost:6274. Mở URL đó, chuyển sang tab Tools, chọn một công cụ (ví dụ: get-template), điền các tham số dưới dạng JSON, và nhấn Run. Phản hồi từ Mailtrap sẽ xuất hiện ở bảng bên dưới.

CLI

Để gọi một lần mà không cần giao diện, hãy dùng npm run mcp:cli. Truyền các cờ CLI của Inspector sau -- để npm chuyển tiếp nguyên văn:

# 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

Chạy MCPB Server

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

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Để phát triển với MCP Inspector:

npm run dev:mcpb

Xử lý lỗi

Server này sử dụng xử lý lỗi có cấu trúc, phù hợp với các quy ước của MCP:

  • VALIDATION_ERROR: Lỗi xác thực đầu vào
  • CONFIGURATION_ERROR: Cấu hình thiếu hoặc không hợp lệ
  • EXECUTION_ERROR: Lỗi thực thi khi chạy
  • TIMEOUT: Hết thời gian thao tác (mặc định 30 giây)

Lỗi bao gồm các thông báo có thể hành động và được ghi lại ở dạng có cấu trúc.

Bảo mật

  • Đầu vào được xác thực qua lược đồ Zod
  • Các biến môi trường được xử lý an toàn
  • Bảo vệ thời gian chờ cho các thao tác (30 giây)
  • Các chi tiết nhạy cảm được làm sạch trong đầu ra lỗi

Ghi nhật ký

Nhật ký JSON có cấu trúc với các mức: INFO, WARN, ERROR, DEBUG.

Bật ghi nhật ký gỡ lỗi bằng cách đặt DEBUG=true.

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

Quan trọng: Server ghi nhật ký vào stderr để stdout luôn dành riêng cho các khung JSON-RPC. Điều này ngăn các host gặp lỗi phân tích JSON do nhật ký bị trộn lẫn.

Ví dụ phân tích nhật ký bằng 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")'

Xử lý sự cố

Các vấn đề thường gặp:

  1. Thiếu API Token: đảm bảo MAILTRAP_API_TOKEN được đặt
  2. Sandbox không hoạt động: cung cấp test_inbox_id trong lệnh gọi công cụ hoặc đặt biến môi trường MAILTRAP_TEST_INBOX_ID
  3. Lỗi hết thời gian: kiểm tra kết nối mạng và trạng thái API của Mailtrap
  4. Lỗi xác thực: đảm bảo tất cả các trường bắt buộc được cung cấp

Đóng góp

Các báo cáo lỗi và yêu cầu kéo luôn được hoan nghênh trên GitHub. Dự án này hướng tới việc trở thành một không gian an toàn, thân thiện cho sự hợp tác, và những người đóng góp được kỳ vọng tuân thủ quy tắc ứng xử.

Giấy phép

Gói này được cung cấp dưới dạng mã nguồn mở theo các điều khoản của MIT License.

Quy tắc ứng xử

Mọi người tương tác trong các mã nguồn, trình theo dõi vấn đề, phòng trò chuyện và danh sách gửi thư của dự án Mailtrap đều được kỳ vọng tuân theo quy tắc ứng xử.