Mailtrap

chính thức

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

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

Gửi email giao dịch — Yêu cầu trợ lý gửi email với tiêu đề và nội dung dạng văn bản hoặc HTML, có thể dùng mẫu và biến.
Kiểm thử trong Email Sandbox — Gửi thư đến sandbox và kiểm tra nội dung, tiêu đề cùng tệp đính kèm mà không gửi đến người nhận thật.
Gỡ lỗi gửi thư bằng nhật ký — Liệt kê và lọc nhật ký email đã gửi, sau đó mở một thư cụ thể để xem lại lịch sử sự kiện và trạng thái gửi.
Phân tích thống kê gửi thư — Xem tỷ lệ gửi thành công, thư bị trả lại, mở, nhấp và thư rác trong một khoảng thời gian, phân tích theo miền, danh mục hoặc ngày.
Quản lý mẫu — Tạo, liệt kê, cập nhật và xóa các mẫu email được lưu trong tài khoản Mailtrap của bạn.
Quản lý miền và danh sách chặn — Liệt kê miền, nhận hướng dẫn thiết lập DNS, đồng thời xem lại hoặc xóa các địa chỉ bị chặn.

Tài liệu

Máy chủ MCP chính thức của Mailtrap

Máy chủ MCP chính thức dành cho Mailtrap — nền tảng gửi email. Máy chủ kết nối tài khoản Mailtrap của bạn với Claude, Cursor, VS Code và các trợ lý AI khác tương thích với MCP.

Gửi email giao dịch và email hàng loạt, kiểm tra tin nhắn an toàn trong Email Sandbox, quản lý mẫu, danh bạ, miền và webhook, xem nhật ký email và thống kê gửi, khắc phục sự cố về khả năng gửi email, đồng thời quản lý tài nguyên tài khoản — tất cả bằng lời nhắc ngôn ngữ tự nhiên.

Khả năng

API email và SMTP — Gửi email giao dịch và email hàng loạt, bao gồm tin nhắn theo lô và dựa trên mẫu.
Kiểm thử email — Kiểm tra tin nhắn trong Email Sandbox và xem nội dung, tiêu đề, tệp đính kèm, điểm spam và khả năng tương thích với ứng dụng email HTML.
Giám sát gửi email — Tìm kiếm nhật ký email, xem lịch sử sự kiện và phân tích tỷ lệ gửi thành công, thư bị trả lại, mở, nhấp và spam.
Cơ sở hạ tầng email — Quản lý miền, xác minh DNS, webhook và danh sách chặn.
Danh bạ — Quản lý danh bạ, danh sách, trường tùy chỉnh và sự kiện, cùng với chức năng nhập và xuất.
Quản lý tài khoản — Xem mức sử dụng thanh toán và quản lý quyền truy cập, quyền hạn, mã thông báo API và tài khoản phụ.

Các ứng dụng MCP được hỗ trợ

Hoạt động với Claude Desktop, Claude Code, Cursor, VS Code và mọi ứng dụng khác tương thích với MCP. Hướng dẫn thiết lập cho từng ứng dụng ở bên dưới.

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

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

Tạo tài khoản Mailtrap
Xác minh miền của bạn
Lấy mã thông báo API từ cài đặt API của Mailtrap
Lấy ID tài khoản từ trang quản lý tài khoản Mailtrap
Cài đặt Node.js phiên bản 22 trở lên, trừ khi bạn chạy ảnh Docker

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 templates, get-sending-stats, nhật ký email, danh sách/xem sandbox, miền và danh sách chặn. Chỉ không bắt buộc đối với các công cụ gửi (send-email, send-sandbox-email và các công cụ batch-send-*), công cụ chiến dịch email, get-marketing-stats, công cụ thông tin công ty, công cụ từ chối theo dõi và list-accounts.

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

DEFAULT_FROM_EMAIL - Địa chỉ email người gửi mặc định khi không truyền from cho send-email, send-sandbox-email hoặc các công cụ batch-send-* (trong đó giá trị này được dùng cho base.from). Cho phép đổi người gửi theo từng lần gọi thông qua tham số from.
MAILTRAP_SANDBOX_ID - ID sandbox mặc định khi không truyền sandbox_id của công cụ (vẫn chấp nhận test_inbox_id cũ trên các công cụ gửi/liệt kê/xem tin nhắn sandbox). Cho phép đổi sandbox theo từng lần gọi thông qua tham số.
MAILTRAP_TEST_INBOX_ID - Bí danh không còn được khuyến nghị của MAILTRAP_SANDBOX_ID; vẫn được đọc làm giá trị dự phòng cho các cấu hình hiện có và ghi cảnh báo không còn được khuyến nghị vào stderr khi sử dụng.
MAILTRAP_ORGANIZATION_ID - Bắt buộc cho các công cụ tổ chức (list-sub-accounts, create-sub-account, delete-sub-account).
MAILTRAP_ORGANIZATION_API_TOKEN - Mã thông báo API trong 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

Docker

Chạy máy chủ qua stdio bằng ảnh Docker MCP Catalog:

docker run --rm -i \
  -e MAILTRAP_API_TOKEN="${MAILTRAP_API_TOKEN}" \
  -e MAILTRAP_ACCOUNT_ID="${MAILTRAP_ACCOUNT_ID}" \
  -e DEFAULT_FROM_EMAIL="${DEFAULT_FROM_EMAIL}" \
  -e MAILTRAP_SANDBOX_ID="${MAILTRAP_SANDBOX_ID}" \
  -e MAILTRAP_ORGANIZATION_ID="${MAILTRAP_ORGANIZATION_ID}" \
  -e MAILTRAP_ORGANIZATION_API_TOKEN="${MAILTRAP_ORGANIZATION_API_TOKEN}" \
  mcp/mailtrap

Xem Điều kiện tiên quyết để biết các biến môi trường bắt buộc và tùy chọn.

Để tạo bản dựng từ kho lưu trữ này: docker build -t mcp/mailtrap .

Smithery CLI

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

Cài đặt máy chủ đã phát hành (mailtrap/mailtrap-mcp) vào ứng dụng cục bộ (thay tên ứng dụng nếu cần):

npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude

Xem tài liệu Smithery CLI để biết các ứng dụng khác (cursor, windsurf, v.v.) và cách phát hành bản cập nhật.

Thiết lập

Claude Desktop

Dùng MCPB để cài đặt máy chủ Mailtrap. Bạn có thể tìm thấy các tệp đó trong Releases.
Tải tệp .MCPB xuống rồi mở tệp. Nếu bạn dùng Claude Desktop, ứng dụng 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_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Nếu bạn dùng asdf để quản lý Node.js, bạn phải 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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_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 lệnh sau trong Command Palette: Preferences: Open User Settings (JSON)

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

{
  "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_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

[!TIP] Đừng quên khởi động lại máy chủ MCP sau khi thay đổi phần "env".

MCP Bundle (MCPB)

Để dễ dàng cài đặt trên các ứng dụng hỗ trợ MCP Bundle, 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. Tập lệnh sao chép dist/, manifest.json, icon.png và giấy phép vào mcpb-build/, cài đặt các phần phụ thuộc production tại đó và chỉ đóng gói thư mục đó. Không chạy mcpb pack . từ thư mục gốc của kho lưu trữ.

Cách sử dụng

Sau khi cấu hình, bạn có thể yêu cầu tác nhân gửi email và quản lý mẫu, chẳng hạn như:

Thao tác gửi email:

"Gửi email cho john.doe@example.com với tiêu đề 'Cuộc họp ngày mai' 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 nhóm tại team@example.com"
"Gửi mẫu chào mừng (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) cho new@example.com với các biến { name: 'Alex' }"
"Gửi email sandbox đến test@example.com với tiêu đề 'Mẫu thử nghiệm' để xem trước email chào mừng của chúng ta"

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

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

Thống kê:

"Lấy thống kê gửi email cho tháng 1 năm 2025"
"Hiển thị tỷ lệ gửi thành công theo miền trong 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ì?"
"Hoạt động tiếp thị qua email của tôi trong tháng trước thế nào? So sánh các chiến dịch với quy trình tự động hóa"

Thao tác với sandbox:

"Lấy tất cả tin nhắn từ sandbox của tôi"
"Hiển thị trang đầu tiên của tin nhắn sandbox"
"Tìm tin nhắn có chứa 'test' trong sandbox của tôi"
"Tạo sandbox tên 'QA' trong dự án 42 và cung cấp thông tin xác thực SMTP"
"Xóa tất cả tin nhắn khỏi sandbox 1234"
"Hiển thị chi tiết tin nhắn sandbox có ID 5159037506"

Thao tác với 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 tên 'Email chào mừng' với tiêu đề 'Chào mừng bạn đến với nền tảng của chúng tôi!'"
"Cập nhật mẫu có ID 12345 để đổi tiêu đề thành 'Lời chào mừng đã cập nhật'"
"Xóa mẫu có ID 67890"

Miền:

"Liệt kê các miền của tôi"
"Lấy miền có ID 3938"
"Tạo miền cho example.com"
"Bật theo dõi lượt nhấp cho miền 3938"
"Xóa miền 3938"
"Lấy miền 3938 cùng hướng dẫn thiết lập DNS"
"Hiển thị thông tin công ty của miền 3938"
"Đặt thông tin công ty cho miền 3938 thành Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
"Đổi thành phố trong thông tin công ty của miền 3938 thành New York"

Danh sách chặn:

"Liệt kê các địa chỉ bị chặn của bounced@example.com"
"Chặn bounced@example.com trên luồng giao dịch của miền 3938"
"Hiển thị tất cả địa chỉ email bị chặn"
"Tại sao user@example.com không nhận được email của tôi?"
"Xóa user@example.com khỏi danh sách chặn"

Từ chối theo dõi:

"Ngừng theo dõi lượt mở và lượt nhấp của privacy@example.com trên miền 3938"
"Liệt kê tất cả những người đã từ chối theo dõi"

Danh bạ và danh sách:

"Thêm john.doe@example.com vào danh sách liên hệ nhận bản tin của tôi"
"Hiển thị tất cả danh sách liên hệ của tôi"
"Tạo trường liên hệ tên 'signup_source' để theo dõi nguồn gốc của các liên hệ"
"Cập nhật liên hệ john.doe@example.com để đặt gói của họ thành 'pro'"
"Nhập danh bạ từ tệp CSV này vào danh sách onboarding của tôi"
"Xuất tất cả danh bạ từ danh sách bản tin của tôi"
"Ghi nhận sự kiện 'trial_started' cho liên hệ john.doe@example.com"

Webhook:

"Liệt kê tất cả webhook được cấu hình trên tài khoản của tôi"
"Tạo webhook trỏ đến https://example.com/hooks/mailtrap cho các sự kiện thư bị trả lại và spam"
"Cập nhật webhook 4821 để gửi thêm cả sự kiện gửi thành công"
"Xóa webhook 4821"

Tài khoản và thanh toán:

"Mức sử dụng thanh toán hiện tại của tôi trong tháng này là bao nhiêu?"
"Tôi còn bao nhiêu email trong gói của mình?"
"Liệt kê tất cả những người có quyền truy cập vào tài khoản Mailtrap này"
"Hiển thị các tài nguyên quyền hạn có trên tài khoản của tôi"

Mã thông báo API:

"Liệt kê tất cả mã thông báo API trên tài khoản của tôi"
"Tạo mã thông báo API mới cho môi trường staging"
"Đặt lại mã thông báo API có ID 1234"
"Xóa mã thông báo API 1234 không còn sử dụng"

Tổ chức và tài khoản phụ:

"Liệt kê tất cả tài khoản phụ trong tổ chức của tôi"
"Tạo tài khoản phụ mới cho dự án khách hàng 'Acme Corp'"

Công cụ đã đổi tên

Mailtrap hiện gọi các hộp thư thử nghiệm là sandboxes và các miền gửi là domains, tên công cụ cũng được đổi theo. Tên cũ không còn xuất hiện trong danh sách công cụ, nhưng các lệnh gọi đến chúng vẫn hoạt động và ghi cảnh báo không còn được khuyến nghị vào stderr. Chúng sẽ bị xóa trong một bản phát hành chính trong tương lai.

Các ứng dụng MCP và khung tác nhân đối chiếu danh sách cho phép, danh sách chặn và danh sách bộ lọc với tên công cụ được công bố, vì vậy hãy chuyển mọi mục theo từng công cụ sang tên mới: mục chặn delete-sending-domain sẽ không còn chặn delete-domain.

Tên cũ	Tên mới
`create-sandbox-inbox`	`create-sandbox`
`get-sandbox-inbox`	`get-sandbox`
`update-sandbox-inbox`	`update-sandbox`
`delete-sandbox-inbox`	`delete-sandbox`
`clean-sandbox-inbox`	`clean-sandbox`
`list-sending-domains`	`list-domains`
`get-sending-domain`	`get-domain`
`create-sending-domain`	`create-domain`
`update-sending-domain`	`update-domain`
`delete-sending-domain`	`delete-domain`
`send-sending-domain-setup-instructions`	`send-domain-setup-instructions`
`sending_domain_id` tham số của các công cụ miền và thông tin công ty	`domain_id`
Biến môi trường `MAILTRAP_TEST_INBOX_ID`	`MAILTRAP_SANDBOX_ID`

Các bộ lọc phản ánh trường API vẫn giữ nguyên tên: sending_domain_id trên list-email-logs và sending_domain_ids trên các công cụ thống kê.

Công cụ hiện có

send-email

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

Tham số:

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

batch-send-transactional-email

Gửi một lô 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 được đặt trong base; các giá trị ghi đè theo từng người nhận được đặt trong requests[]. Mỗi yêu cầu phải có ít nhất một người nhận thông qua to, cc hoặc bcc. Áp dụng cùng quy tắc loại trừ lẫn nhau giữa nội dung trực tiếp và mẫu như send-email — được kiểm tra sau khi hợp nhất dữ liệu cơ sở với từng yêu cầu.

Tham số:

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

batch-send-bulk-email

Gửi một lô email hàng loạt thông qua API luồng gửi hàng loạt của Mailtrap. Có cùng cấu trúc base + requests[], quy tắc xác thực và quy tắc nội dung trực tiếp so với 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 điểm cuối gửi hàng loạt thay vì điểm cuối 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) với các tùy chọn phân trang và bộ lọc. Dùng để gỡ lỗi sự cố gửi email ngay trong IDE.

Tham số:

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

Tất cả tham số đều không bắt buộc.

get-email-log-message

Lấy một thư trong nhật ký email theo ID (UUID): bản tóm tắt dễ đọc (người gửi, người nhận, chủ đề, 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. Nếu có include_content: true, bạn cũng có thể tải và hiển thị nội dung thư (HTML và văn bản thuần) khi Mailtrap cung cấp URL thư thô.

Tham số:

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

get-sending-stats

Lấy thống kê gửi email (tỷ lệ gửi thành công, thư bị trả lại, mở, nhấp, thư rác) trong một khoảng ngày. Có thể tùy chọn phân tích 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 của khoảng thống kê (YYYY-MM-DD)
end_date (bắt buộc): Ngày kết thúc của khoảng thống kê (YYYY-MM-DD)
breakdown (không bắt buộc): Cách phân tích thống kê: aggregated (mặc định), by_domain, by_category, by_email_service_provider hoặc by_date
sending_domain_ids (không bắt buộc): Giới hạn kết quả ở các ID miền này (mảng số nguyên)
sending_streams (không bắt buộc): Giới hạn ở transactional và/hoặc bulk (mảng chuỗi)
categories (không bắt buộc): Giới hạn ở các danh mục email này (mảng chuỗi)
email_service_providers (không bắt buộc): Giới hạn ở các nhà cung cấp này, ví dụ: Google, Yahoo, Outlook (mảng chuỗi)

get-marketing-stats

Lấy thống kê Email Marketing tổng hợp trên các chiến dịch và quy trình tự động hóa trong một khoảng ngày: số lượng và tỷ lệ gửi, gửi thành công, thư bị trả lại, mở, nhấp, thư rác và hủy đăng ký. delivery_rate và bounce_rate là tỷ lệ trên sent_count; các tỷ lệ còn lại là tỷ lệ trên delivery_count.

Tham số:

start_date (bắt buộc): Ngày bắt đầu của khoảng thời gian (bao gồm), YYYY-MM-DD
end_date (bắt buộc): Ngày kết thúc của khoảng thời gian (bao gồm), YYYY-MM-DD
sending_domain_ids (không bắt buộc): Giới hạn kết quả ở các ID miền này (mảng số nguyên)
sources (không bắt buộc): campaigns hoặc automations sẽ thu hẹp thống kê vào nguồn đó; bỏ qua hoặc truyền cả hai để lấy toàn bộ lưu lượng Email Marketing (mảng chuỗi)
email_service_providers (không bắt buộc): Giới hạn ở các nhà cung cấp này, ví dụ: Google, Yahoo, Outlook (mảng chuỗi)

create-template

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

Tham số:

name (bắt buộc): Tên 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 (không bắt buộc): Danh mục mẫu (mặc định là "General")

list-templates

Liệt kê các mẫu email trong tài khoản Mailtrap của bạn với phân trang bằng mã thông báo trang. Khi còn mẫu khác, kết quả sẽ nêu token cho trang tiếp theo. Các trang là các khoảng bù trừ trong danh sách sắp xếp từ mới nhất đến cũ nhất, vì vậy sau khi xóa mẫu, hãy liệt kê lại từ token 1 thay vì tiếp tục bằng mã thông báo tiếp theo; trang trống sẽ nêu trang cuối cùng vẫn còn mẫu.

Tham số:

token (không bắt buộc): Số trang cần truy xuất (phân trang bằng mã thông báo trang). Mặc định là 1
per_page (không bắt buộc): Số mẫu trên mỗi trang. Mặc định là 50, tối đa 100. Truyền cùng một giá trị cho mọi trang

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 (không bắt buộc): Tên mới cho mẫu
subject (không bắt buộc): Dòng chủ đề email mới
html (không bắt buộc): Nội dung HTML mới của mẫu
text (không bắt buộc): Phiên bản văn bản thuần mới của mẫu
category (không bắt buộc): Danh mục mới cho mẫu

[!NOTE] Khi gọi update-template để thực hiện cập nhật, phải cung cấp ít nhất một trường có thể cập nhật (name, subject, html, text hoặc category).

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 sandbox Mailtrap của bạn để phát triển và kiểm thử. Đây là lựa chọn lý tưởng để kiểm thử mẫu email mà không gửi email đến người nhận thật. Hỗ trợ cùng hai chế độ như send-email — nội dung trực tiếp hoặc dựa trên mẫu (template_uuid).

Tham số:

sandbox_id (tùy chọn): Ưu tiên dùng. ID sandbox Mailtrap. Bắt buộc trừ khi đã đặt MAILTRAP_SANDBOX_ID.
test_inbox_id (tùy chọn): Bí danh cũ của sandbox_id khi bỏ qua sandbox_id.
from (tùy chọn): Người gửi dưới dạng { email, name? } (khi chạy cũng chấp nhận chuỗi email thuần). Nếu không cung cấp, sẽ dùng DEFAULT_FROM_EMAIL.
to (tùy chọn): Mảng người nhận dưới dạng các đối tượng { email, name? } (khi chạy cũng chấp nhận chuỗi email thuần trong mảng hoặc chuỗi email thuần được phân tách bằng dấu phẩy). Không bắt buộc nếu cung cấp cc hoặc bcc; ít nhất một trong 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? } (khi chạy cũng chấp nhận chuỗi email thuần).
bcc (tùy chọn): Mảng người nhận BCC dưới dạng các đối tượng { email, name? } (khi chạy cũng chấp nhận chuỗi email thuần).
subject (có điều kiện): Dòng tiêu đề email. Bắt buộc khi gửi nội dung trực tiếp; phải bỏ qua khi đã đặt template_uuid.
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) khi gửi nội dung trực tiếp; phải bỏ qua khi đã đặt template_uuid.
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) khi gửi nội dung trực tiếp; phải bỏ qua khi đã đặt template_uuid.
category (tùy chọn): Danh mục email dùng để theo dõi. Phải bỏ qua khi đã đặt template_uuid.
template_uuid (tùy chọn): Dùng mẫu email Mailtrap thay cho nội dung trực tiếp. Khi được đặt, phải bỏ qua subject / text / html / category.
template_variables (tùy chọn): Đối tượng chứa các biến được thay thế vào mẫu được tham chiếu bởi template_uuid. Chỉ được phép dùng cùng với template_uuid.

batch-send-sandbox-email

Gửi một loạt email đến sandbox Mailtrap của bạn trong một lệnh gọi API mà không gửi đến người nhận thực. Có cùng cấu trúc base + requests[], quy tắc xác thực và quy tắc gửi nội dung trực tiếp so với dùng 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 endpoint sandbox cho một sandbox duy nhất.

Tham số:

sandbox_id (tùy chọn): ID sandbox Mailtrap. Bắt buộc trừ khi đã đặt MAILTRAP_SANDBOX_ID; truyền vào trong từng lệnh gọi để nhắm đến một sandbox cụ thể.
base (tùy chọn), requests (bắt buộc): Xem phần batch-send-transactional-email ở trên.

[!NOTE] Hầu hết công cụ sandbox sử dụng sandbox_id (hoặc dùng giá trị dự phòng MAILTRAP_SANDBOX_ID; env không còn được khuyến nghị MAILTRAP_TEST_INBOX_ID vẫn hoạt động). send-sandbox-email, get-sandbox-messages và show-sandbox-email-message cũng chấp nhận test_inbox_id cũ. get-sandbox, update-sandbox, delete-sandbox và clean-sandbox sử dụng sandbox_id cùng với inbox_id cũ (cùng một ID; inbox_id không được dùng trong các công cụ xử lý thư). Công cụ email đến sử dụng inbox_id cho một sản phẩm khác (thư đã nhận), không phải sandbox.

get-sandbox-messages

Lấy danh sách thư từ sandbox Mailtrap của bạn. Hữu ích để kiểm tra những email đã được nhận trong sandbox trong quá trình thử nghiệm.

Tham số:

sandbox_id (tùy chọn): Ưu tiên dùng. ID sandbox, trừ khi đã đặt MAILTRAP_SANDBOX_ID.
test_inbox_id (tùy chọn): Bí danh cũ của sandbox_id.
page (tùy chọn): Số trang để phân trang (tối thiểu: 1)
last_id (tùy chọn): Phân trang bằng ID thư cuối cùng. Trả về các thư sau ID thư được chỉ định (tối thiểu: 1)
search (tùy chọn): Truy vấn tìm kiếm để lọc thư

[!NOTE] Có thể bỏ qua các tham số ID sandbox khi đã đặt MAILTRAP_SANDBOX_ID. Nếu không cung cấp sandbox_id, test_inbox_id hoặc env, lệnh gọi sẽ thất bại. Phân trang: sử dụng page, last_id hoặc search tùy nhu cầu.

show-sandbox-email-message

Hiển thị thông tin chi tiết và nội dung của một email cụ thể trong sandbox Mailtrap, bao gồm nội dung HTML và văn bản.

Tham số:

sandbox_id (tùy chọn): Ưu tiên dùng. ID sandbox, trừ khi đã đặt MAILTRAP_SANDBOX_ID.
test_inbox_id (tùy chọn): Bí danh cũ của sandbox_id.
message_id (bắt buộc): ID của email sandbox cần truy xuất

[!NOTE] Trước tiên, dùng get-sandbox-messages để lấy ID thư, sau đó dùng công cụ này để xem toàn bộ nội dung.

list-sandbox-projects

Liệt kê tất cả dự án sandbox và các sandbox của chúng.

Tham số:

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

create-sandbox-project

Tạo dự án sandbox mới để nhóm các sandbox.

Tham số:

name (bắt buộc): Tên dự án (2–100 ký tự)

get-sandbox-project

Lấy dự án sandbox theo ID, bao gồm các sandbox 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 của dự án (2–100 ký tự)

delete-sandbox-project

Xóa một dự án sandbox và tất cả sandbox trong dự án đó.

Tham số:

project_id (bắt buộc): ID của dự án cần xóa

create-sandbox

Tạo sandbox mới trong một dự án. Trả về thông tin xác thực SMTP mới của sandbox.

Tham số:

project_id (bắt buộc): ID của dự án nơi tạo sandbox
name (bắt buộc): Tên sandbox

get-sandbox

Lấy thông tin chi tiết về sandbox, bao gồm thông tin xác thực SMTP, số lượng email và trạng thái.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Bắt buộc trừ khi đã đặt MAILTRAP_SANDBOX_ID.
inbox_id (tùy chọn): Bí danh cũ của sandbox_id.

update-sandbox

Cập nhật tên hoặc tên người dùng email của sandbox.

Tham số:

sandbox_id (bắt buộc): ID sandbox (bí danh cũ: inbox_id)
name (tùy chọn): Tên mới của sandbox
email_username (tùy chọn): Tên người dùng email mới của sandbox

Phải cung cấp ít nhất một trong name hoặc email_username.

delete-sandbox

Xóa sandbox và tất cả thư trong đó.

Tham số:

sandbox_id (bắt buộc): ID sandbox (bí danh cũ: inbox_id)

clean-sandbox

Xóa tất cả thư khỏi sandbox mà không xóa chính sandbox đó.

Tham số:

sandbox_id (bắt buộc): ID sandbox (bí danh cũ: inbox_id)

list-sandboxes

Liệt kê mọi sandbox mà token API có quyền truy cập trong tất cả dự án.

Tham số:

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

mark-sandbox-as-read

Đánh dấu tất cả thư trong 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 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 sandbox (bật địa chỉ Mailtrap chuyển thư đế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 địa chỉ nhận email mới cho 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 thư trong sandbox đến một địa chỉ email bên ngoài. 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ùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư sandbox cần chuyển tiếp
email (bắt buộc): Địa chỉ email nhận thư được chuyển tiếp

update-sandbox-message

Đánh dấu thư trong sandbox là đã đọc hoặc chưa đọc.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư 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ư trong sandbox.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư sandbox cần xóa

get-sandbox-message-spam-score

Lấy báo cáo spam SpamAssassin cho một thư trong sandbox (điểm số, quy tắc, báo cáo đầy đủ). Phương án độc lập thay cho include_spam_report: true trên show-sandbox-email-message.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-html-analysis

Lấy báo cáo phân tích HTML cho một thư trong sandbox (điểm tương thích với ứng dụng email, các phần tử có vấn đề). Phương án độc lập thay cho include_html_analysis: true trên show-sandbox-email-message.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-headers

Lấy các tiêu đề thư đã phân tích cú pháp của một thư trong sandbox.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-html

Lấy nội dung HTML đã kết xuất của một thư trong sandbox.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-text

Lấy nội dung văn bản thuần của một thư trong sandbox.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-raw

Lấy thư ở định dạng MIME thô (tiêu đề + nội dung) trong sandbox.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-eml

Lấy thư được kết xuất dưới dạng dữ liệu tệp EML (phù hợp để đính kèm vào phiếu hỗ trợ hoặc nhập vào ứng dụng email khác).

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-message-html-source

Lấy mã nguồn HTML chưa kết xuất của một thư trong sandbox (HTML trước mọi biến đổi phía Mailtrap như viết lại liên kết CID).

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

list-sandbox-attachments

Liệt kê tất cả tệp đính kèm của một thư trong 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ùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư trong sandbox

get-sandbox-attachment

Lấy siêu dữ liệu và URL tải xuống của một tệp đính kèm.

Tham số:

sandbox_id (tùy chọn): ID sandbox. Dùng giá trị dự phòng MAILTRAP_SANDBOX_ID.
message_id (bắt buộc): ID của thư 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-domains

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

Tham số:

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

get-domain

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

Tham số:

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

create-domain

Tạo miền mới. Sau khi tạo, hãy thêm các bản ghi DNS để xác minh miền (dùng get-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)

update-domain

Cập nhật cài đặt theo dõi và thư đến của một miền.

Tham số:

domain_id (bắt buộc): ID miền (bí danh cũ: sending_domain_id)
open_tracking_enabled (không bắt buộc): Theo dõi lượt mở email được gửi từ miền này
click_tracking_enabled (không bắt buộc): Theo dõi lượt nhấp vào liên kết trong email được gửi từ miền này
tracking_opt_out_enabled (không bắt buộc): Thêm liên kết từ chối theo dõi vào email được theo dõi. Yêu cầu bật theo dõi lượt mở hoặc lượt nhấp
auto_unsubscribe_link_enabled (không bắt buộc): Tự động thêm liên kết hủy đăng ký vào email
inbound_enabled (không bắt buộc): Cho phép gắn miền này với hộp thư đến để nhận tất cả thư

Phải cung cấp ít nhất một cài đặt ngoài domain_id.

delete-domain

Xóa một miền.

Tham số:

domain_id (bắt buộc): ID miền cần xóa (bí danh cũ: sending_domain_id)

send-domain-setup-instructions

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

Tham số:

domain_id (bắt buộc): ID miền (bí danh cũ: sending_domain_id)
email (bắt buộc): Địa chỉ email nhận hướng dẫn thiết lập DNS

get-company-info

Lấy thông tin công ty của một miền, dùng để xác minh tuân thủ miền.

Tham số:

domain_id (bắt buộc): ID miền (bí danh cũ: sending_domain_id)

create-company-info

Thiết lập thông tin công ty của một miền, cần thiết để xác minh tuân thủ miền.

Tham số:

domain_id (bắt buộc): ID miền (bí danh cũ: sending_domain_id)
name (bắt buộc): Tên công ty hoặc cá nhân
address (bắt buộc): Địa chỉ đường phố
city (bắt buộc): Thành phố
country (bắt buộc): Quốc gia
zip_code (bắt buộc): Mã ZIP hoặc mã bưu chính
website_url (bắt buộc): URL trang web của công ty
phone (không bắt buộc): Số điện thoại
privacy_policy_url (không bắt buộc): URL trang chính sách quyền riêng tư
terms_of_service_url (không bắt buộc): URL trang điều khoản dịch vụ
info_level (không bắt buộc): business hoặc individual

update-company-info

Cập nhật thông tin công ty của một miền.

Tham số:

domain_id (bắt buộc): ID miền (bí danh cũ: sending_domain_id)
Tất cả các trường của create-company-info đều không bắt buộc. Phải cung cấp ít nhất một trường; các trường bị bỏ qua sẽ không thay đổi.

list-suppressions

Liệt kê hoặc tìm kiếm các mục trong danh sách chặn (email bị trả lại vĩnh viễn, khiếu nại spam, hủy đăng ký, nhập thủ công). Mỗi lần gọi trả về tối đa 1000 kết quả.

Tham số:

email (không bắt buộc): Bộ lọc email. Chỉ trả về các mục trong danh sách chặn khớp với địa chỉ này.

create-suppression

Thêm địa chỉ email vào danh sách chặn của tài khoản để Mailtrap ngừng gửi email đến địa chỉ đó.

Tham số:

email (bắt buộc): Địa chỉ email cần chặn
domain_id (bắt buộc): ID miền áp dụng mục chặn này
sending_stream (bắt buộc): transactional hoặc bulk
type (không bắt buộc): hard bounce, spam complaint, unsubscription hoặc manual import. Mặc định là manual import

delete-suppression

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

Tham số:

suppression_id (bắt buộc): ID của mục chặn cần xóa

list-tracking-opt-outs

Liệt kê các địa chỉ email bị loại trừ khỏi việc theo dõi lượt mở và lượt nhấp. Mỗi lần gọi trả về tối đa 1000 bản ghi.

Tham số:

email (không bắt buộc): Bộ lọc email. Chỉ trả về các mục từ chối theo dõi khớp với địa chỉ này
start_time (không bắt buộc): Chỉ lấy các mục từ chối theo dõi được tạo vào hoặc sau thời điểm này (ISO 8601)
end_time (không bắt buộc): Chỉ lấy các mục từ chối theo dõi được tạo vào hoặc trước thời điểm này (ISO 8601)
last_id (không bắt buộc): Con trỏ phân trang — last_id từ phản hồi trước đó

create-tracking-opt-out

Loại trừ một địa chỉ email khỏi việc theo dõi lượt mở và lượt nhấp đối với một miền.

Tham số:

email (bắt buộc): Địa chỉ email từ chối theo dõi
domain_id (bắt buộc): ID miền áp dụng mục từ chối theo dõi này

delete-tracking-opt-out

Xóa một địa chỉ email khỏi danh sách từ chối theo dõi để tiếp tục áp dụng việc theo dõi lượt mở và lượt nhấp cho địa chỉ đó.

Tham số:

tracking_opt_out_id (bắt buộc): ID của mục từ chối theo dõi 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 — 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 webhook. Phản hồi bao gồm signing_secret để xác minh chữ ký của tải trọng webhook — bí mật này chỉ được trả về khi tạo, vì vậy hãy lưu lại ngay. Nếu làm mất, 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 (không bắt buộc, boolean): mặc định là true
payload_format (không bắt buộc): "json" hoặc "jsonlines". Mặc định là "json"
sending_stream (không bắt buộc, chỉ dành cho email_sending): "transactional" hoặc "bulk"
event_types (không bắt buộc, chỉ dành cho email_sending): mảng gồm delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
domain_id (không bắt buộc, chỉ dành cho email_sending): ID miền để giới hạn webhook này
inbound_inbox_id (không bắt buộc, chỉ dành cho inbound_receiving): ID hộp thư đến được liên kết với webhook; 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. Không thể thay đổi webhook_type, sending_stream và domain_id sau khi tạo — hãy tạo lại webhook nếu 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 (không bắt buộc): URL webhook mới
active (không bắt buộc, boolean): Bật hoặc tắt webhook
payload_format (không bắt buộc): "json" hoặc "jsonlines"
event_types (không bắt buộc, chỉ dành cho email_sending): mảng gồm delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
inbound_inbox_id (không bắt buộc, chỉ dành cho inbound_receiving): ID hộp thư đến được liên kết với webhook

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 một liên hệ theo ID hoặc email. Trả về toàn bộ bản ghi liên hệ (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 liên hệ mới.

Tham số:

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

update-contact

Cập nhật một liên hệ hiện có được xác định bằng ID hoặc email. list_ids thay thế toàn bộ tập hợp danh sá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 các mục còn lại.

Tham số:

contact_identifier (bắt buộc): ID liên hệ hoặc email
email (không bắt buộc): Địa chỉ email mới
fields (không bắt buộc): Giá trị trường tùy chỉnh, được ánh xạ theo thẻ hợp nhất
list_ids (không bắt buộc): Thay thế tập hợp danh sách thành viên bằng chính xác danh sách này
list_ids_included (không bắt buộc): ID danh sách cần thêm (bổ sung)
list_ids_excluded (không bắt buộc): ID danh sách cần xóa
unsubscribed (không bắt buộc, 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 nếu API phản hồi bản ghi đó; nếu không, trả về tải trọng xác nhận.

Tham số:

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

create-contact-event

Ghi nhận một sự kiện liên hệ cho một liên hệ (theo ID hoặc email). 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 các điều kiện kích hoạt tự động hóa)
params (bắt buộc): Đối tượng gồm 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 (không bắt buộc): Lọc danh sách liên hệ theo tên (khớp không phân biệt chữ hoa chữ thường), ví dụ: news

get-contact-list

Lấy 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 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 đị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 chỗ giữ 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 chỗ giữ 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 đị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 (không bắt buộc): Tên hiển thị mới
merge_tag (không bắt buộc): Thẻ hợp nhất mới (phải tiếp tục là duy nhất)
data_type (không bắt buộc): Một trong các giá trị text, number, boolean, date

delete-contact-field

Xóa vĩnh viễn đị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 tác vụ nhập; kiểm tra trạng thái 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 của liên hệ
- fields (không bắt buộc): Giá trị trường tùy chỉnh, được ánh xạ theo thẻ hợp nhất (giá trị dạng chuỗi hoặc số)
- list_ids_included (không bắt buộc): ID danh sách cần thêm liên hệ vào
- list_ids_excluded (không bắt buộc): ID danh sách cần xóa liên hệ khỏi

get-contact-import

Lấy trạng thái của tác vụ nhập liên hệ (created/started/finished/failed) cùng số lượng đã tạo/cập nhật/vượt giới hạn.

Tham số:

import_id (bắt buộc): ID của tác vụ 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 bộ lọc kết hợp bằng AND. Trả về bản ghi tác vụ 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 đối tượng có:
- name (bắt buộc): Trường cần 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 tác vụ xuất danh bạ. 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 tác vụ xuất danh bạ

list-email-campaigns

Liệt kê các chiến dịch email của tài khoản, mới nhất trước, với phân trang bằng mã thông báo trang. Có thể lọc theo tên bằng search.

Tham số:

token (không bắt buộc): Số trang cần truy xuất (phân trang bằng mã thông báo trang). Mặc định là 1
per_page (không bắt buộc): Số chiến dịch mỗi trang. Mặc định là 50, tối đa 100
search (không bắt buộc): Lọc chiến dịch theo tên (khớp một phần, không phân biệt chữ hoa chữ thường)

get-email-campaign

Lấy chiến dịch email theo ID.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email

create-email-campaign

Tạo chiến dịch email mới. Chiến dịch luôn được tạo ở trạng thái draft; việc lên lịch và bắt đầu được thực hiện bằng các công cụ riêng (schedule-email-campaign, start-email-campaign).

Tham số:

name (bắt buộc): Tên chiến dịch
domain_id (bắt buộc): ID của miền đã xác minh dùng cho chiến dịch, như được trả về bởi list-domains
from_local_part (bắt buộc): Phần cục bộ (trước dấu @) của địa chỉ Người gửi
template_attributes (bắt buộc): Mẫu email nội tuyến. Bao gồm:
- subject (bắt buộc): Dòng tiêu đề email (tối đa 255 ký tự). Hỗ trợ thẻ hợp nhất, ví dụ Hi {{first_name}}
- body_html (không bắt buộc): Nội dung HTML (thiết kế). Bắt buộc trước khi có thể lên lịch hoặc bắt đầu chiến dịch. Thêm liên kết hủy đăng ký bằng một thẻ neo có href chứa phần giữ chỗ __unsubscribe_url__
- body_text (không bắt buộc): Bản thay thế dạng văn bản thuần của nội dung email
- merge_tags (không bắt buộc): Tên thuần của các thẻ hợp nhất được tham chiếu trong tiêu đề/nội dung, ví dụ ["first_name"]
from_display_name (không bắt buộc): Tên hiển thị trong tiêu đề Người gửi
reply_to (không bắt buộc): Các phần của địa chỉ Trả lời đến (display_name, local_part, domain)
delivery_mode (không bắt buộc): rapid (gửi nhanh nhất có thể) hoặc gradual (giới hạn tốc độ ở mức delivery_options.emails_per_hour)
delivery_options (không bắt buộc): Tùy chọn giới hạn tốc độ gửi (emails_per_hour)
contact_list_ids (không bắt buộc): ID của các danh sách liên hệ sẽ gửi đến (được xem là toàn bộ tập hợp danh sách được bao gồm)
contact_segment_ids (không bắt buộc): ID của các phân khúc liên hệ sẽ gửi đến (được xem là toàn bộ tập hợp phân khúc được bao gồm)

update-email-campaign

Cập nhật chiến dịch email draft. Chỉ các trường được cung cấp mới thay đổi; mẫu được chỉnh sửa tại chỗ. Không thể cập nhật chiến dịch ở bất kỳ trạng thái nào khác.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần cập nhật
Tất cả tham số khác đều không bắt buộc và giống với create-email-campaign (name, domain_id, from_local_part, from_display_name, reply_to, template_attributes, delivery_mode, delivery_options, contact_list_ids, contact_segment_ids)

delete-email-campaign

Xóa chiến dịch email theo ID. Chỉ có thể xóa chiến dịch ở trạng thái draft.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần xóa

start-email-campaign

Bắt đầu gửi ngay chiến dịch email draft. Chỉ có thể bắt đầu các chiến dịch draft; mẫu phải có thiết kế body_html, đồng thời phải thiết lập đối tượng nhận và miền đã xác minh.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần bắt đầu

schedule-email-campaign

Lên lịch bắt đầu gửi chiến dịch email draft vào một thời điểm trong tương lai. Chỉ có thể lên lịch cho các chiến dịch draft.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần lên lịch
datetime (bắt buộc): Thời điểm gửi chiến dịch (ISO 8601). Phải là thời điểm trong tương lai và không quá 1 tháng kể từ hiện tại

cancel-email-campaign

Hủy chiến dịch email scheduled, đưa chiến dịch trở lại trạng thái draft. Chỉ có thể hủy các chiến dịch scheduled.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần hủy

terminate-email-campaign

Chấm dứt chiến dịch email hiện đang gửi (started, queued hoặc paused), hủy lần gửi đang diễn ra.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần chấm dứt

reset-email-campaign

Đặt lại chiến dịch email scheduled về trạng thái draft. Chỉ có thể đặt lại các chiến dịch scheduled.

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email cần đặt lại

get-email-campaign-stats

Lấy số liệu thống kê hiệu suất tổng hợp của một chiến dịch email (số lượng và tỷ lệ gửi thành công, mở, nhấp, thư bị trả lại, khiếu nại spam và hủy đăng ký).

Tham số:

email_campaign_id (bắt buộc): ID của chiến dịch email
start_date (không bắt buộc): Thời điểm bắt đầu khoảng thời gian tổng hợp (bao gồm), YYYY-MM-DD. Mặc định là ngày chiến dịch được bắt đầu gần nhất
end_date (không bắt buộc): Thời điểm kết thúc khoảng thời gian tổng hợp (bao gồm), YYYY-MM-DD. Mặc định là ngày hiện tại

list-accounts

Liệt kê các tài khoản Mailtrap mà mã thông báo API hiện tại có thể truy cập, cùng với cấp độ truy cập của từng tài khoản. Hoạt động mà không cần MAILTRAP_ACCOUNT_ID, vì vậy hãy dùng công cụ này để tìm ID tài khoản của bạn.

Tham số:

Không cần tham số

get-billing-usage

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

Tham số:

Không cần tham số

list-account-accesses

Liệt kê quyền truy cập tài khoản (người dùng, lời mời, mã thông báo API) của tài khoản. Có thể dùng bộ lọc tùy chọn để giới hạn 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 (không bắt buộc): Lọc theo UUID miền (mảng chuỗi)
inbox_ids (không bắt buộc): Lọc theo ID sandbox (mảng chuỗi)
project_ids (không bắt buộc): 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. Với các đối tượng chỉ định User, thao tác này thu hồi quyền của họ; với các đối tượng chỉ định Invite hoặc ApiToken, thao tác này xóa hoàn toàn đối tượng chỉ đị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 (sandbox, dự án, miền, thanh toán, tài khoản) mà mã thông báo API có quyền quản trị, được lồng theo cấu trúc phân cấp.

Tham số:

Không cần 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. 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 quyền 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 (không bắt buộc): admin/100 hoặc viewer/10
- destroy (không bắt buộc, boolean): Khi là true, xóa quyền này thay vì tạo/cập nhật quyền

list-api-tokens

Liệt kê tất cả mã thông báo API của tài khoản.

Tham số:

Không cần tham số

create-api-token

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

Tham số:

name (bắt buộc): Tên hiển thị của mã thông báo
expires_at (không bắt buộc): Thời hạn hết hạn của mã thông báo dưới dạng ngày giờ ISO 8601. Bỏ qua để dùng mặc định của máy chủ (1 năm); truyền null tường minh để tạo mã thông báo không bao giờ hết hạn. Các giá trị trong quá khứ hoặc cách hiện tại hơn 5 năm sẽ bị từ chối
resources (không bắt buộc): Mảng quyền tài nguyên để giới hạn phạm vi của mã thông báo. 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ị viên) hoặc 10 (người xem)

get-api-token

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

Tham số:

api_token_id (bắt buộc): ID của mã thông báo API

reset-api-token

Đặt lại (xoay vòng) mã thông báo API 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 ngay. Mã thông báo trước đó sẽ bị vô hiệu hóa.

Tham số:

api_token_id (bắt buộc): ID của mã thông báo API cần đặt lại
expires_at (không bắt buộc): Thời hạn hết hạn của mã thông báo mới dưới dạng ngày giờ ISO 8601. Bỏ qua để dùng mặc định của máy chủ (1 năm); truyền null tường minh để tạo mã thông báo không bao giờ hết hạn. Các giá trị trong quá khứ hoặc cách hiện tại hơn 5 năm sẽ bị từ chối

delete-api-token

Xóa vĩnh viễn mã thông báo API theo ID. Sau khi bị xóa, mã thông báo không thể dùng để xác thực nữa.

Tham số:

api_token_id (bắt buộc): ID của mã thông báo API cần xóa

list-sub-accounts

Liệt kê các tài khoản phụ 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 phụ.

Tham số:

Không cần tham số

create-sub-account

Tạo tài khoản phụ 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 phụ.

Tham số:

name (bắt buộc): Tên hiển thị của tài khoản phụ mới

delete-sub-account

Xóa vĩnh viễn tài khoản phụ theo ID, đồng thời xóa toàn bộ dữ liệu của tài khoản đó. Xóa tài khoản phụ cuối cùng sẽ xóa tổ chức; gọi lại sẽ trả về 404. Nếu có thao tác xóa đồng thời cùng một tài khoản phụ, yêu cầu sẽ trả về 409. Yêu cầu biến môi trường MAILTRAP_ORGANIZATION_ID và quyền quản trị tổ chức; tổ chức cũng phải bật tính năng Organization & Sub-accounts (nếu không sẽ trả về 403).

Tham số:

sub_account_id (bắt buộc): ID của tài khoản phụ cần xóa

list-inbound-folders

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

Tham số:

Không cần tham số

get-inbound-folder

Lấy một thư mục nhận theo ID. Trả về toàn bộ bản ghi thư mục dưới dạng JSON.

Tham số:

folder_id (bắt buộc): ID của thư mục nhận

create-inbound-folder

Tạo thư mục nhận mới.

Tham số:

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

update-inbound-folder

Đổi tên thư mục nhận.

Tham số:

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

delete-inbound-folder

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

Tham số:

folder_id (bắt buộc): ID của thư mục nhận

list-inbound-inboxes

Liệt kê tất cả hộp thư trong một thư mục nhận. 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 nhận

get-inbound-inbox

Lấy một hộp thư nhận theo ID. Trả về toàn bộ bản ghi hộp thư dưới dạng JSON.

Tham số:

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

create-inbound-inbox

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

Tham số:

folder_id (bắt buộc): ID của thư mục thư đến
name (bắt buộc): Tên hộp thư đến
domain_id (không bắt buộc): Gắn với miền tùy chỉnh (hộp thư nhận tất cả). Bỏ qua nếu dùng hộp thư do Mailtrap lưu trữ

update-inbound-inbox

Đổi tên hộp thư đến.

Tham số:

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

delete-inbound-inbox

Xóa vĩnh viễn hộp thư đến.

Tham số:

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

list-inbound-messages

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

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
last_id (không bắt buộc): Con trỏ phân trang từ last_id của phản hồi trước đó

get-inbound-message

Lấy một thư đến cùng toàn bộ nội dung và URL tải xuống tệp đính kèm. Trả về bản ghi thư đầy đủ dưới dạng JSON.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
message_id (bắt buộc): ID của thư

delete-inbound-message

Xóa vĩnh viễn một thư đến.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
message_id (bắt buộc): ID của thư

reply-to-inbound-message

Trả lời thư đến (gửi cho người gửi ban đầu). Thao tác này gửi email thật. Địa chỉ có thể là chuỗi email thuần hoặc { email, name? }.

Tham số:

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

reply-all-to-inbound-message

Trả lời thư đến và gửi bản sao cho những người nhận khác trong thư gốc. Thao tác này gửi email thật. Dùng cùng các tham số như reply-to-inbound-message.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
message_id (bắt buộc): ID của thư cần trả lời
Cùng các trường gửi không bắt buộc như reply-to-inbound-message

forward-inbound-message

Chuyển tiếp thư đến cho người nhận mới. Thao tác này gửi email thật.

Tham số:

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

list-inbound-threads

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

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
last_id (không bắt buộc): Con trỏ phân trang từ last_id của phản hồi trước đó
search (không bắt buộc): Văn bản không phân biệt chữ hoa chữ thường, được so khớp với chủ đề của chuỗi hội thoại và các địa chỉ from/to/cc/bcc trong thư của chuỗi đó. Truyền cùng giá trị khi phân trang

get-inbound-thread

Lấy một chuỗi hội thoại đến cùng các thư được nhúng trong đó (từ cũ nhất đến mới nhất). Trả về bản ghi chuỗi hội thoại đầy đủ dưới dạng JSON.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
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 đến.

Tham số:

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

list-inbound-forward-rules

Liệt kê các quy tắc chuyển tiếp của hộp thư đến. Trả về bản tóm tắt được định dạng.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến

get-inbound-forward-rule

Lấy một quy tắc chuyển tiếp đến theo ID. Trả về bản ghi quy tắc đầy đủ dưới dạng JSON, bao gồm các điều kiện và đích nhận.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
forward_rule_id (bắt buộc): ID của quy tắc chuyển tiếp

create-inbound-forward-rule

Tạo quy tắc chuyển tiếp cho hộp thư đến. Các thư đã nhận khớp với tất cả điều kiện sẽ được chuyển tiếp đến các đích nhận của quy tắc.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
name (bắt buộc): Tên quy tắc, duy nhất trong hộp thư
conditions (không bắt buộc): Mảng { match_type, operator, value?, header_key? }. match_type là sender, recipient hoặc header; operator là equal, not_equal, contains, starts_with, ends_with, empty hoặc not_empty (empty/not_empty chỉ áp dụng cho header và không nhận value); header_key là bắt buộc đối với header. Bỏ qua hoặc truyền [] để khớp với mọi thư
destinations (không bắt buộc): Mảng { email } để chuyển tiếp các thư khớp điều kiện đến

update-inbound-forward-rule

Cập nhật quy tắc chuyển tiếp đến. Chỉ các trường được cung cấp mới thay đổi; nếu cung cấp mảng conditions hoặc destinations, toàn bộ tập hợp tương ứng sẽ được thay thế.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
forward_rule_id (bắt buộc): ID của quy tắc chuyển tiếp
name (không bắt buộc): Tên quy tắc mới
conditions (không bắt buộc): Tập hợp điều kiện thay thế (cùng cấu trúc như khi tạo); [] sẽ xóa mọi điều kiện, khiến quy tắc khớp với mọi thư
destinations (không bắt buộc): Tập hợp đích nhận thay thế; [] sẽ xóa mọi đích nhận

delete-inbound-forward-rule

Xóa vĩnh viễn một quy tắc chuyển tiếp đến.

Tham số:

inbox_id (bắt buộc): ID của hộp thư đến
forward_rule_id (bắt buộc): ID của quy tắc chuyển tiếp

Phát triển

Sao chép kho lưu trữ:

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

Cài đặt các phần 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 Thiết lập.

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_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Nếu bạn dùng asdf để quản lý Node.js, hãy 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/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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

VS Code

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

{
  "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_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

Kiểm thử

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

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

Cả hai cách đều yêu cầu phải build gói trước:

npm run build

và xuất MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID trong shell (tập lệnh mcp:cli chuyển tiếp cả hai biến này đến máy chủ được 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 thẻ Tools, chọn một công cụ (ví dụ: get-template), điền các tham số dưới dạng JSON rồi nhấn Run. Phản hồi từ Mailtrap sẽ xuất hiện trong bảng bên dưới.

CLI

Để thực hiện lệnh gọi một lần mà không dùng 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-domain-setup-instructions \
  --tool-arg domain_id=3938 \
  --tool-arg email=devops@example.com

Chạy máy chủ MCPB

# 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

Máy chủ này sử dụng cơ chế 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 bị thiếu hoặc không hợp lệ
EXECUTION_ERROR: Lỗi thực thi trong thời gian chạy
TIMEOUT: Hết thời gian chờ thao tác (mặc định 30 giây)

Lỗi bao gồm thông báo có hướng dẫn xử lý và được ghi nhật ký theo cấu trúc.

Bảo mật

Xác thực đầu vào bằng lược đồ Zod
Xử lý biến môi trường an toàn
Bảo vệ thao tác bằng giới hạn thời gian chờ (30 giây)
Làm sạch thông tin nhạy cảm trong đầu ra lỗi

Ghi nhật ký

Nhật ký JSON có cấu trúc với các cấp độ: 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: Máy chủ ghi nhật ký vào stderr để stdout được dành riêng cho các khung JSON-RPC. Điều này ngăn máy chủ chủ gặp lỗi phân tích cú pháp JSON do nhật ký bị xen 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")'

Khắc phục sự cố

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

Thiếu API Token: đảm bảo đã đặt MAILTRAP_API_TOKEN
Sandbox không hoạt động: cung cấp sandbox_id trong lệnh gọi công cụ (hoặc test_inbox_id cũ trên các công cụ gửi/liệt kê/hiển thị thư), hoặc đặt biến môi trường MAILTRAP_SANDBOX_ID
Lỗi hết thời gian chờ: kiểm tra kết nối mạng và trạng thái API Mailtrap
Lỗi xác thực: đảm bảo đã cung cấp tất cả các trường bắt buộc

Đóng góp

Chúng tôi hoan nghênh báo cáo lỗi và yêu cầu kéo trên GitHub. Dự án này hướng đến việc tạo ra một không gian cộng tác an toàn, thân thiện; 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 là phần mềm mã nguồn mở, được cung cấp theo các điều khoản của Giấy phép MIT.

Quy tắc ứng xử

Mọi người tham gia vào các kho 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 thủ quy tắc ứng xử.