Mailtrap MCP Server

resmi

Terintegrasi dengan Mailtrap Email API.

GitHub
60

Dokumentasi

TypeScript test NPM

Server MCP Mailtrap

Server MCP yang menyediakan alat untuk mengirim dan menguji di sandbox melalui Mailtrap.

Prasyarat

Sebelum menggunakan server MCP ini, Anda perlu:

  1. Membuat akun Mailtrap
  2. Memverifikasi domain Anda
  3. Mendapatkan token API dari Pengaturan API Mailtrap
  4. Mendapatkan ID Akun dari Manajemen akun Mailtrap

Variabel Lingkungan yang Diperlukan:

  • MAILTRAP_API_TOKEN - Diperlukan untuk semua fungsionalitas
  • MAILTRAP_ACCOUNT_ID - Diperlukan untuk template, statistik, log email, daftar/tampilkan sandbox, dan domain pengiriman. Opsional hanya untuk send-email dan send-sandbox-email.

Opsional (dapat diberikan sebagai parameter alat):

  • DEFAULT_FROM_EMAIL - Email pengirim default saat from tidak diberikan ke send-email atau send-sandbox-email. Memungkinkan penggantian pengirim per panggilan melalui parameter from.
  • MAILTRAP_TEST_INBOX_ID - ID kotak masuk uji default untuk alat sandbox saat test_inbox_id tidak diberikan. Memungkinkan perpindahan antar kotak masuk per panggilan melalui parameter test_inbox_id.
  • MAILTRAP_SANDBOX_ID - ID sandbox default untuk alat sandbox saat sandbox_id tidak diberikan. Memungkinkan perpindahan antar sandbox per panggilan melalui parameter sandbox_id.
  • MAILTRAP_ORGANIZATION_ID - Diperlukan untuk alat organisasi (list-sub-accounts, create-sub-account).
  • MAILTRAP_ORGANIZATION_API_TOKEN - Token API dengan cakupan organisasi. Diperlukan untuk alat organisasi (terpisah dari MAILTRAP_API_TOKEN).

Instalasi Cepat

Install in Cursor

Install with Node in VS Code

Smithery CLI

Smithery adalah penginstal dan pengelola registri untuk server MCP yang bekerja dengan semua klien AI.

npx @smithery/cli install mailtrap

Smithery secara otomatis menangani konfigurasi klien dan menyediakan proses pengaturan interaktif. Ini adalah cara termudah untuk memulai dengan server MCP secara lokal.

Pengaturan

Claude Desktop

Gunakan MCPB untuk menginstal server Mailtrap. Anda dapat menemukan file tersebut di Rilis.
Unduh file .MCPB dan buka. Jika Anda memiliki Claude Desktop - itu akan membukanya dan menyarankan untuk mengonfigurasi.

Claude Desktop atau Cursor

Tambahkan konfigurasi berikut:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Jika Anda menggunakan asdf untuk mengelola Node.js, Anda harus menggunakan jalur absolut ke executable (contoh untuk 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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Lokasi file konfigurasi Claude Desktop

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Lokasi file konfigurasi Cursor

Mac: ~/.cursor/mcp.json

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

VS Code

Mengubah konfigurasi secara manual

Jalankan di Palet Perintah: Preferences: Open User Settings (JSON)

Kemudian, di file pengaturan, tambahkan konfigurasi berikut:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

[!TIP] Jangan lupa untuk memulai ulang server MCP Anda setelah mengubah bagian "env".

MCP Bundle (MCPB)

Untuk instalasi mudah di host yang mendukung MCP Bundles, Anda dapat mendistribusikan file 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

Ini membuat mailtrap-mcp.mcpb menggunakan repositori manifest.json dan artefak yang dibangun di dist/.

Penggunaan

Setelah dikonfigurasi, Anda dapat meminta agen untuk mengirim email dan mengelola template, misalnya:

Operasi Pengiriman Email:

  • "Kirim email ke [email protected] dengan subjek 'Meeting Tomorrow' dan pengingat ramah tentang pertemuan kita yang akan datang."
  • "Email [email protected] tentang pembaruan proyek, dan CC tim di [email protected]"
  • "Kirim template selamat datang (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) ke [email protected] dengan variabel { name: 'Alex' }"
  • "Kirim email sandbox ke [email protected] dengan subjek 'Test Template' untuk melihat pratinjau tampilan email selamat datang kita"

Log Email (debug pengiriman):

  • "Daftar log email terkirim terbaru saya"
  • "Tampilkan log email untuk email yang dikirim ke [email protected]"
  • "Dapatkan pesan log email untuk ID abc-123-uuid untuk memeriksa status pengiriman"

Statistik Pengiriman:

  • "Dapatkan statistik pengiriman untuk Januari 2025"
  • "Tampilkan tingkat pengiriman yang dipecah berdasarkan domain untuk bulan lalu"
  • "Apa statistik email saya berdasarkan kategori dari 2025-01-01 hingga 2025-01-31?"

Operasi Sandbox:

  • "Dapatkan semua pesan dari kotak masuk sandbox saya"
  • "Tampilkan halaman pertama pesan sandbox"
  • "Cari pesan yang mengandung 'test' di kotak masuk sandbox saya"
  • "Tampilkan detail pesan sandbox dengan ID 5159037506"

Operasi Template:

  • "Daftar semua template email di akun Mailtrap saya"
  • "Buat template email baru bernama 'Welcome Email' dengan subjek 'Welcome to our platform!'"
  • "Perbarui template dengan ID 12345 untuk mengubah subjek menjadi 'Updated Welcome Message'"
  • "Hapus template dengan ID 67890"

Domain Pengiriman:

  • "Daftar domain pengiriman saya"
  • "Dapatkan domain pengiriman dengan ID 3938"
  • "Buat domain pengiriman untuk example.com"
  • "Hapus domain pengiriman 3938"
  • "Dapatkan domain pengiriman 3938 dengan instruksi pengaturan DNS"

Alat yang Tersedia

send-email

Mengirim email transaksional melalui Mailtrap. Mendukung dua mode yang saling eksklusif — konten inline (subject + text/html) atau berbasis template (template_uuid).

Parameter:

  • from (opsional): Pengirim sebagai string email atau { email, name? }. Jika tidak diberikan, DEFAULT_FROM_EMAIL digunakan.
  • to (opsional): Penerima — satu email/{ email, name? } atau array. Opsional jika cc atau bcc diberikan; setidaknya satu dari to / cc / bcc harus berisi penerima.
  • cc (opsional): Array penerima CC (string email atau { email, name? } masing-masing).
  • bcc (opsional): Array penerima BCC (string email atau { email, name? } masing-masing).
  • subject (bersyarat): Baris subjek email. Diperlukan untuk pengiriman inline; harus dihilangkan saat template_uuid diatur.
  • text (bersyarat): Teks isi email. Diperlukan (bersama atau sebagai pengganti html) untuk pengiriman inline; harus dihilangkan saat template_uuid diatur.
  • html (bersyarat): Versi HTML dari isi email. Diperlukan (bersama atau sebagai pengganti text) untuk pengiriman inline; harus dihilangkan saat template_uuid diatur.
  • category (opsional): Kategori email untuk pelacakan dan analitik. Harus dihilangkan saat template_uuid diatur.
  • template_uuid (opsional): Gunakan template email Mailtrap alih-alih konten inline. Saat diatur, subject / text / html / category harus dihilangkan (sesuai API Mailtrap).
  • template_variables (opsional): Objek variabel yang disubstitusi ke dalam template yang dirujuk oleh template_uuid. Hanya diizinkan bersama dengan template_uuid.

batch-send-transactional-email

Mengirim batch email transaksional dalam satu panggilan API Mailtrap (aliran pengiriman default). Bidang bersama ada di base; penggantian per penerima ada di requests[]. Setiap permintaan harus menyertakan setidaknya satu penerima melalui to, cc, atau bcc. Pengecualian mutual inline-vs-template yang sama seperti send-email — diperiksa setelah menggabungkan basis dengan setiap permintaan.

Parameter:

  • base (opsional): Objek dengan bidang yang dibagikan di seluruh batch.
    • from (opsional): Pengirim sebagai string email atau { email, name? }. Kembali ke DEFAULT_FROM_EMAIL.
    • reply_to (opsional): Alamat balasan.
    • subject / text / html / category (opsional, mode inline): Konten default untuk setiap permintaan.
    • template_uuid / template_variables (opsional, mode template): Template default + variabel. Saling eksklusif dengan bidang inline.
    • custom_variables (opsional): Variabel kustom default (bernilai string).
    • headers (opsional): Header kustom default.
  • requests (diperlukan): Array tidak kosong dari pesan per penerima. Setiap entri memiliki:
    • to (opsional): Penerima — string, { email, name? }, atau array. Opsional jika cc atau bcc diberikan; setidaknya satu dari to / cc / bcc harus berisi penerima.
    • cc, bcc, reply_to (opsional).
    • Penggantian inline (subject/text/html/category) atau template (template_uuid/template_variables); bidang apa pun yang dihilangkan kembali ke nilai base yang cocok.
    • custom_variables, headers (opsional).

batch-send-bulk-email

Mengirim batch email massal melalui API aliran massal Mailtrap. Bentuk base + requests[], validasi, dan aturan inline-vs-template yang sama seperti batch-send-transactional-email — satu-satunya perbedaan adalah alat ini mengarahkan panggilan melalui endpoint massal, bukan yang transaksional. Lihat parameter di atas.

list-email-logs

Mendaftar log email terkirim (riwayat pengiriman) dengan paginasi dan filter opsional. Gunakan untuk men-debug masalah pengiriman dari IDE.

Parameter:

  • search_after (opsional): Kursor paginasi dari next_page_cursor respons sebelumnya
  • sent_after (opsional): Tanggal/waktu ISO 8601; hanya log yang dikirim setelah waktu ini
  • sent_before (opsional): Tanggal/waktu ISO 8601; hanya log yang dikirim sebelum waktu ini
  • from_email (opsional): Filter berdasarkan email pengirim; gunakan dengan from_operator (default: ci_equal)
  • to_email (opsional): Filter berdasarkan email penerima; gunakan dengan to_operator (default: ci_equal)
  • status (opsional): Filter berdasarkan status pengiriman: delivered, not_delivered, enqueued, opted_out; gunakan dengan status_operator (default: equal)
  • subject (opsional): Filter berdasarkan subjek email; gunakan dengan subject_operator (default: ci_contain). Gunakan subject_operator: empty/not_empty untuk memfilter berdasarkan keberadaan subjek.
  • sending_domain_id (opsional): Filter berdasarkan ID domain pengiriman (angka); gunakan dengan sending_domain_id_operator (default: equal)
  • sending_stream (opsional): Filter berdasarkan aliran: transactional atau bulk; gunakan dengan sending_stream_operator (default: equal)
  • events (opsional): Filter berdasarkan jenis peristiwa: delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; gunakan dengan events_operator (include_event / not_include_event)
  • clicks_count / opens_count (opsional): Filter berdasarkan jumlah klik/buka; gunakan dengan *_operator: equal, greater_than, less_than
  • client_ip / sending_ip (opsional): Filter berdasarkan IP; gunakan dengan *_operator: equal, not_equal, contain, not_contain
  • email_service_provider_response (opsional): Filter berdasarkan teks respons penyedia; gunakan dengan *_operator (ci_contain, dll.)
  • email_service_provider (opsional): Filter berdasarkan penyedia (tepat); gunakan dengan *_operator: equal, not_equal
  • recipient_mx (opsional): Filter berdasarkan MX penerima; gunakan dengan recipient_mx_operator (ci_contain, dll.)
  • category (opsional): Filter berdasarkan kategori email; gunakan dengan category_operator: equal, not_equal

Semua parameter bersifat opsional.

get-email-log-message

Mendapatkan satu pesan log email berdasarkan ID (UUID): ringkasan yang dapat dibaca (dari, ke, subjek, waktu kirim, status, kategori, aliran, keterlibatan, konteks pengiriman), kemudian riwayat peristiwa terperinci. Secara opsional, dengan include_content: true, Anda juga dapat memuat dan menampilkan isi pesan (HTML dan teks biasa) saat Mailtrap mengekspos URL pesan mentah.

Parameter:

  • message_id (diperlukan): UUID dari pesan log email (dari respons kirim atau list-email-logs). Gunakan list-email-logs untuk menemukan ID pesan.
  • include_content (opsional): Saat true, mengambil EML mentah (jika raw_message_url tersedia) dan menambahkan bagian isi HTML dan teks biasa yang diurai, mirip dengan show-sandbox-email-message.

get-sending-stats

Dapatkan statistik pengiriman email (tingkat pengiriman, bouncing, buka, klik, spam) untuk rentang tanggal. Secara opsional, pecah berdasarkan domain, kategori, penyedia layanan email, atau tanggal. Periksa tingkat pengiriman tanpa meninggalkan editor.

Parameter:

  • start_date (wajib): Tanggal mulai untuk rentang statistik (YYYY-MM-DD)
  • end_date (wajib): Tanggal akhir untuk rentang statistik (YYYY-MM-DD)
  • breakdown (opsional): Cara mengelompokkan statistik: aggregated (bawaan), by_domain, by_category, by_email_service_provider, atau by_date
  • sending_domain_ids (opsional): Batasi hasil ke ID domain pengirim ini (array bilangan bulat)
  • sending_streams (opsional): Batasi ke transactional dan/atau bulk (array string)
  • categories (opsional): Batasi ke kategori email ini (array string)
  • email_service_providers (opsional): Batasi ke penyedia ini, misalnya Google, Yahoo, Outlook (array string)

create-template

Membuat template email baru di akun Mailtrap Anda.

Parameter:

  • name (wajib): Nama template
  • subject (wajib): Baris subjek email
  • html (atau text wajib): Konten HTML template
  • text (atau html wajib): Versi teks biasa template
  • category (opsional): Kategori template (bawaan "General")

list-templates

Mencantumkan semua template email di akun Mailtrap Anda.

Parameter:

  • Tidak ada parameter yang diperlukan

get-template

Mendapatkan satu template email berdasarkan ID, termasuk subjek, kategori, dan isi HTML/teks.

Parameter:

  • template_id (wajib): ID template yang akan diambil

update-template

Memperbarui template email yang sudah ada.

Parameter:

  • template_id (wajib): ID template yang akan diperbarui
  • name (opsional): Nama baru untuk template
  • subject (opsional): Baris subjek email baru
  • html (opsional): Konten HTML baru template
  • text (opsional): Versi teks biasa baru template
  • category (opsional): Kategori baru untuk template

[!NOTE] Setidaknya satu bidang yang dapat diperbarui (nama, subjek, html, teks, atau kategori) harus disediakan saat memanggil update-template untuk melakukan pembaruan.

delete-template

Menghapus template email yang sudah ada.

Parameter:

  • template_id (wajib): ID template yang akan dihapus

send-sandbox-email

Mengirim email ke kotak masuk uji Mailtrap Anda untuk keperluan pengembangan dan pengujian. Ini sempurna untuk menguji template email tanpa mengirim email ke penerima sebenarnya. Mendukung dua mode yang sama seperti send-email — konten sebaris atau berbasis template (template_uuid).

Parameter:

  • test_inbox_id (opsional): ID kotak masuk uji Mailtrap. Wajib kecuali MAILTRAP_TEST_INBOX_ID diatur; berikan per panggilan untuk menargetkan kotak masuk tertentu.
  • from (opsional): Pengirim sebagai string email atau { email, name? }. Jika tidak disediakan, DEFAULT_FROM_EMAIL digunakan.
  • to (opsional): Penerima sebagai string yang dipisahkan koma, atau array string email / objek { email, name? }. Opsional jika cc atau bcc disediakan; setidaknya satu dari to / cc / bcc harus berisi penerima.
  • cc (opsional): Array penerima CC (masing-masing string email atau { email, name? }).
  • bcc (opsional): Array penerima BCC (masing-masing string email atau { email, name? }).
  • subject (bersyarat): Baris subjek email. Wajib untuk pengiriman sebaris; harus dihilangkan saat template_uuid diatur.
  • text (bersyarat): Teks isi email. Wajib (bersama atau sebagai pengganti html) untuk pengiriman sebaris; harus dihilangkan saat template_uuid diatur.
  • html (bersyarat): Versi HTML isi email. Wajib (bersama atau sebagai pengganti text) untuk pengiriman sebaris; harus dihilangkan saat template_uuid diatur.
  • category (opsional): Kategori email untuk pelacakan. Harus dihilangkan saat template_uuid diatur.
  • template_uuid (opsional): Gunakan template email Mailtrap alih-alih konten sebaris. Saat diatur, subject / text / html / category harus dihilangkan.
  • template_variables (opsional): Objek variabel yang disubstitusikan ke dalam template yang dirujuk oleh template_uuid. Hanya diizinkan bersama template_uuid.

[!NOTE] Untuk alat sandbox, berikan test_inbox_id dalam panggilan alat atau atur variabel lingkungan MAILTRAP_TEST_INBOX_ID. Anda dapat beralih antar kotak masuk per panggilan dengan memberikan test_inbox_id.

get-sandbox-messages

Mengambil daftar pesan dari kotak masuk uji Mailtrap Anda. Berguna untuk memeriksa email apa yang telah diterima di sandbox Anda selama pengujian.

Parameter:

  • page (opsional): Nomor halaman untuk paginasi (minimum: 1)
  • last_id (opsional): Paginasi menggunakan ID pesan terakhir. Mengembalikan pesan setelah ID pesan yang ditentukan (minimum: 1)
  • search (opsional): Kueri pencarian untuk memfilter pesan

[!NOTE] Semua parameter bersifat opsional. Jika tidak ada yang disediakan, halaman pertama pesan dari kotak masuk akan dikembalikan. Gunakan page untuk paginasi tradisional, last_id untuk paginasi berbasis kursor, atau search untuk memfilter pesan berdasarkan konten.

show-sandbox-email-message

Menampilkan informasi detail dan konten pesan email tertentu dari kotak masuk uji Mailtrap Anda, termasuk konten isi HTML dan teks.

Parameter:

  • message_id (wajib): ID pesan email sandbox yang akan diambil

[!NOTE] Gunakan get-sandbox-messages terlebih dahulu untuk mendapatkan daftar pesan dan ID-nya, lalu gunakan alat ini untuk melihat konten lengkap pesan tertentu.

get-sandbox-project

Mendapatkan proyek sandbox berdasarkan ID, termasuk kotak masuk dan jumlah emailnya.

Parameter:

  • project_id (wajib): ID proyek yang akan diambil

update-sandbox-project

Mengganti nama proyek sandbox yang sudah ada.

Parameter:

  • project_id (wajib): ID proyek yang akan diperbarui
  • name (wajib): Nama baru untuk proyek (2–100 karakter)

list-sandboxes

Mencantumkan setiap sandbox yang dapat diakses oleh token API di semua proyek.

Parameter:

  • Tidak ada parameter yang diperlukan

mark-sandbox-as-read

Menandai semua pesan di sandbox sebagai telah dibaca.

Parameter:

  • sandbox_id (wajib): ID sandbox yang akan ditindaklanjuti

reset-sandbox-credentials

Mengatur ulang kredensial SMTP untuk sandbox. Mengembalikan nama pengguna/kata sandi baru.

Parameter:

  • sandbox_id (wajib): ID sandbox yang akan ditindaklanjuti

enable-sandbox-email-address

Mengaktifkan alamat terima-lewat-email untuk sandbox (mengaktifkan alamat Mailtrap yang mengirimkan pesan ke sandbox melalui SMTP).

Parameter:

  • sandbox_id (wajib): ID sandbox yang akan ditindaklanjuti

reset-sandbox-email-address

Menghasilkan alamat terima-lewat-email baru untuk sandbox.

Parameter:

  • sandbox_id (wajib): ID sandbox yang akan ditindaklanjuti

forward-sandbox-message

Meneruskan pesan sandbox ke alamat email eksternal. Dihitung terhadap kuota penerusan bulanan Anda.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox yang akan diteruskan
  • email (wajib): Alamat email tujuan penerusan pesan

update-sandbox-message

Menandai pesan sandbox sebagai telah dibaca atau belum dibaca.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox yang akan diperbarui
  • is_read (wajib): true menandai sebagai telah dibaca, false menandai sebagai belum dibaca

delete-sandbox-message

Menghapus satu pesan sandbox.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox yang akan dihapus

get-sandbox-message-spam-score

Mendapatkan laporan spam SpamAssassin untuk pesan sandbox (skor, aturan, laporan lengkap). Alternatif mandiri untuk include_spam_report: true pada show-sandbox-email-message.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-html-analysis

Mendapatkan laporan analisis HTML untuk pesan sandbox (skor kompatibilitas klien, elemen bermasalah). Alternatif mandiri untuk include_html_analysis: true pada show-sandbox-email-message.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-headers

Mendapatkan header email yang diurai untuk pesan sandbox.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-html

Mendapatkan isi HTML yang dirender dari pesan sandbox.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-text

Mendapatkan isi teks biasa dari pesan sandbox.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-raw

Mendapatkan pesan mentah berformat MIME (header + isi) untuk pesan sandbox.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-eml

Mendapatkan pesan yang dirender sebagai payload file EML (cocok untuk dilampirkan ke tiket atau diimpor ke klien email lain).

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-message-html-source

Mendapatkan sumber HTML yang belum dirender dari pesan sandbox (HTML sebelum transformasi sisi Mailtrap seperti penulisan ulang tautan CID).

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

list-sandbox-attachments

Mencantumkan semua lampiran pada pesan sandbox (nama file, tipe konten, ukuran, jalur unduhan).

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox

get-sandbox-attachment

Mendapatkan metadata dan URL unduhan untuk satu lampiran.

Parameter:

  • sandbox_id (opsional): ID Sandbox. Kembali ke MAILTRAP_SANDBOX_ID.
  • message_id (wajib): ID pesan sandbox yang berisi lampiran
  • attachment_id (wajib): ID lampiran yang akan diambil

list-sending-domains

Mencantumkan domain pengirim dan status verifikasi DNS-nya.

Parameter:

  • Tidak ada parameter yang diperlukan

get-sending-domain

Mendapatkan domain pengirim berdasarkan ID dan status verifikasinya (termasuk catatan DNS). Secara opsional sertakan instruksi pengaturan DNS dengan mengatur include_setup_instructions ke true.

Parameter:

  • sending_domain_id (wajib): ID domain pengirim
  • include_setup_instructions (opsional): Jika true, tambahkan instruksi pengaturan DNS ke respons. Bawaan: false

create-sending-domain

Membuat domain pengirim baru. Setelah pembuatan, tambahkan catatan DNS untuk memverifikasi domain (gunakan get-sending-domain dengan include_setup_instructions: true untuk melihat catatannya).

Parameter:

  • domain_name (wajib): Nama domain (misalnya example.com)

delete-sending-domain

Menghapus domain pengirim.

Parameter:

  • sending_domain_id (wajib): ID domain pengirim yang akan dihapus

send-sending-domain-setup-instructions

Mengirim instruksi pengaturan DNS untuk domain pengirim ke alamat tertentu melalui email. Berguna untuk meneruskan catatan DNS ke rekan DevOps.

Parameter:

  • sending_domain_id (wajib): ID domain pengirim
  • email (wajib): Alamat email tujuan pengiriman instruksi pengaturan DNS

list-suppressions

Mencantumkan atau mencari suppressions (hard bounce, keluhan spam, berhenti berlangganan, impor manual). Mengembalikan hingga 1000 hasil per panggilan.

Parameter:

  • email (opsional): Filter email. Hanya mengembalikan suppressions yang cocok dengan alamat ini.

delete-suppression

Hapus suppression berdasarkan ID. Mailtrap akan melanjutkan pengiriman ke email ini kecuali jika suppression terjadi lagi.

Parameter:

  • suppression_id (wajib): ID suppression yang akan dihapus

list-webhooks

Daftarkan semua webhook yang dikonfigurasi untuk akun. Mengembalikan catatan webhook lengkap sebagai JSON.

Parameter:

  • Tidak ada parameter yang diperlukan

get-webhook

Dapatkan satu webhook berdasarkan ID. Mengembalikan catatan webhook lengkap sebagai JSON. Catatan: signing_secret tidak dikembalikan di sini — ini hanya tersedia dalam respons dari create-webhook.

Parameter:

  • webhook_id (wajib): ID webhook yang akan diambil

create-webhook

Buat webhook. Respons mencakup signing_secret untuk memverifikasi tanda tangan payload webhook — rahasia ini dikembalikan hanya saat pembuatan, jadi simpan sekarang. Jika hilang, buat ulang webhook.

Parameter:

  • url (wajib): URL tempat Mailtrap akan mengirimkan event webhook melalui POST
  • webhook_type (wajib): "email_sending" atau "audit_log"
  • active (opsional, boolean): default ke true
  • payload_format (opsional): "json" atau "jsonlines". Default ke "json"
  • sending_stream (opsional, hanya email_sending): "transactional" atau "bulk"
  • event_types (opsional, hanya email_sending): array dari delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject
  • domain_id (opsional, hanya email_sending): ID domain pengirim untuk membatasi cakupan webhook ini

update-webhook

Perbarui bidang yang dapat diubah dari webhook. webhook_type, sending_stream, dan domain_id tidak dapat diubah setelah pembuatan — buat ulang webhook jika perlu mengubahnya.

Parameter:

  • webhook_id (wajib): ID webhook yang akan diperbarui
  • url (opsional): URL webhook baru
  • active (opsional, boolean): Aktifkan atau nonaktifkan webhook
  • payload_format (opsional): "json" atau "jsonlines"
  • event_types (opsional, hanya email_sending): array dari delivery, soft_bounce, bounce, suspension, unsubscribe, open, spam_complaint, click, reject

delete-webhook

Hapus webhook secara permanen berdasarkan ID. Mengembalikan catatan webhook yang dihapus.

Parameter:

  • webhook_id (wajib): ID webhook yang akan dihapus

get-contact

Dapatkan kontak berdasarkan ID atau email. Mengembalikan catatan kontak lengkap (keanggotaan daftar, status, bidang kustom).

Parameter:

  • contact_identifier (wajib): ID kontak atau alamat email

create-contact

Buat kontak baru.

Parameter:

  • email (wajib): Alamat email
  • fields (opsional): Nilai bidang kustom yang dikunci dengan merge tag (mis. first_name). Nilai string, angka, atau boolean
  • list_ids (opsional): ID daftar kontak untuk mendaftarkan kontak ini
  • unsubscribed (opsional, boolean): Buat kontak dalam status unsubscribed

update-contact

Perbarui kontak yang ada yang diidentifikasi berdasarkan ID atau email. list_ids menggantikan set keanggotaan lengkap kontak; list_ids_included/list_ids_excluded menambah/menghapus tanpa mengganggu sisanya.

Parameter:

  • contact_identifier (wajib): ID kontak atau email
  • email (opsional): Alamat email baru
  • fields (opsional): Nilai bidang kustom yang dikunci dengan merge tag
  • list_ids (opsional): Ganti set keanggotaan dengan daftar persis ini
  • list_ids_included (opsional): ID daftar untuk ditambahkan (aditif)
  • list_ids_excluded (opsional): ID daftar untuk dihapus
  • unsubscribed (opsional, boolean): Atur ke unsubscribed (true) atau subscribed (false)

delete-contact

Hapus kontak secara permanen berdasarkan ID atau email. Mengembalikan catatan kontak yang dihapus saat API merespons dengan satu; jika tidak, mengembalikan payload konfirmasi.

Parameter:

  • contact_identifier (wajib): ID kontak atau email

create-contact-event

Catat event kontak terhadap kontak (berdasarkan ID atau email). Digunakan untuk memicu otomatisasi daftar kontak.

Parameter:

  • contact_identifier (wajib): ID kontak atau email
  • name (wajib): Nama event (cocok dengan pemicu otomatisasi)
  • params (wajib): Objek pasangan kunci/nilai arbitrer. Nilai dapat berupa string, angka, boolean, atau null

list-contact-lists

Daftarkan semua daftar kontak untuk akun.

Parameter:

  • Tidak ada parameter yang diperlukan

get-contact-list

Dapatkan daftar kontak berdasarkan ID.

Parameter:

  • list_id (wajib): ID daftar kontak yang akan diambil

create-contact-list

Buat daftar kontak baru.

Parameter:

  • name (wajib): Nama untuk daftar baru

update-contact-list

Ganti nama daftar kontak yang ada.

Parameter:

  • list_id (wajib): ID daftar kontak
  • name (wajib): Nama baru untuk daftar

delete-contact-list

Hapus daftar kontak secara permanen berdasarkan ID.

Parameter:

  • list_id (wajib): ID daftar kontak yang akan dihapus

list-contact-fields

Daftarkan semua definisi bidang kontak untuk akun.

Parameter:

  • Tidak ada parameter yang diperlukan

get-contact-field

Dapatkan definisi bidang kontak berdasarkan ID.

Parameter:

  • field_id (wajib): ID bidang kontak

create-contact-field

Buat definisi bidang kontak baru. merge_tag harus unik dalam akun dan digunakan sebagai nama placeholder dalam variabel template.

Parameter:

  • name (wajib): Nama tampilan (mis. "Nama Depan")
  • merge_tag (wajib): Nama placeholder unik (mis. first_name)
  • data_type (wajib): Salah satu dari text, number, boolean, date

update-contact-field

Perbarui definisi bidang kontak. Kombinasi apa pun dari name, merge_tag, dan data_type dapat diubah.

Parameter:

  • field_id (wajib): ID bidang kontak
  • name (opsional): Nama tampilan baru
  • merge_tag (opsional): Merge tag baru (harus tetap unik)
  • data_type (opsional): Salah satu dari text, number, boolean, date

delete-contact-field

Hapus definisi bidang kontak secara permanen berdasarkan ID.

Parameter:

  • field_id (wajib): ID bidang kontak yang akan dihapus

create-contact-import

Impor kontak secara massal. Mengembalikan catatan pekerjaan impor; periksa statusnya dengan get-contact-import.

Parameter:

  • contacts (wajib): Array entri kontak. Setiap entri memerlukan:
    • email (wajib): Alamat email kontak
    • fields (opsional): Nilai bidang kustom yang dikunci dengan merge tag (nilai string atau angka)
    • list_ids_included (opsional): ID daftar untuk menambahkan kontak
    • list_ids_excluded (opsional): ID daftar untuk menghapus kontak

get-contact-import

Dapatkan status pekerjaan impor kontak (dibuat/dimulai/selesai/gagal) dengan jumlah dibuat/diperbarui/melebihi batas.

Parameter:

  • import_id (wajib): ID pekerjaan impor kontak

create-contact-export

Ekspor kontak yang cocok dengan sekumpulan filter yang digabungkan dengan AND. Mengembalikan catatan pekerjaan ekspor; periksa status dengan get-contact-export untuk mengambil URL unduhan setelah status adalah finished.

Parameter:

  • filters (wajib): Array objek filter. Masing-masing memiliki:
    • name (wajib): Bidang yang akan difilter (list_id, subscription_status, email, dll.)
    • operator (wajib): Salah satu dari equal, not_equal, contains, not_contains, is_empty, is_not_empty
    • value (wajib): Nilai perbandingan (string, angka, boolean, atau array)

get-contact-export

Dapatkan status pekerjaan ekspor kontak. Setelah status adalah finished, bidang url menyimpan tautan unduhan CSV.

Parameter:

  • export_id (wajib): ID pekerjaan ekspor kontak

list-accounts

Daftarkan akun Mailtrap yang dapat diakses oleh token API saat ini, dengan tingkat akses setiap akun.

Parameter:

  • Tidak ada parameter yang diperlukan

get-billing-usage

Dapatkan penggunaan siklus penagihan saat ini untuk akun: paket pengiriman dan pengujian, batas, dan jumlah saat ini.

Parameter:

  • Tidak ada parameter yang diperlukan

list-account-accesses

Daftarkan akses akun (pengguna, undangan, token API) untuk akun. Filter opsional mempersempit hasil ke sumber daya tertentu. Memerlukan izin admin/pemilik akun.

Parameter:

  • domain_uuids (opsional): Filter berdasarkan UUID domain pengirim (array string)
  • inbox_ids (opsional): Filter berdasarkan ID kotak masuk sandbox (array string)
  • project_ids (opsional): Filter berdasarkan ID proyek sandbox (array string)

remove-account-access

Hapus akses akun berdasarkan ID. Untuk penentu User ini mencabut izin mereka; untuk penentu Invite atau ApiToken ini menghapus penentu sepenuhnya. Memerlukan admin/pemilik.

Parameter:

  • account_access_id (wajib): ID catatan akses yang akan dihapus

get-permission-resources

Dapatkan semua sumber daya (kotak masuk, proyek, domain, penagihan, akun) yang memiliki akses admin oleh token API, bersarang berdasarkan hierarki.

Parameter:

  • Tidak ada parameter yang diperlukan

bulk-update-permissions

Buat, perbarui, atau hapus izin secara massal untuk satu akses akun. Pasangan (resource_type, resource_id) yang ada diperbarui; yang baru dibuat. Atur destroy: true pada entri untuk menghapusnya.

Parameter:

  • account_access_id (wajib): ID akses akun target
  • permissions (wajib): Array entri izin. Masing-masing memiliki:
    • resource_id (wajib): ID sumber daya (angka atau string)
    • resource_type (wajib): Salah satu dari account, project, inbox, domain, billing
    • access_level (opsional): admin/100 atau viewer/10
    • destroy (opsional, boolean): Jika true, hapus izin ini alih-alih membuat/memperbaruinya

list-api-tokens

Daftarkan semua token API untuk akun.

Parameter:

  • Tidak ada parameter yang diperlukan

create-api-token

Buat token API baru. Respons mencakup nilai rahasia token — ini adalah satu-satunya waktu token lengkap dikembalikan, jadi segera simpan. Jika hilang, buat ulang token.

Parameter:

  • name (wajib): Nama tampilan untuk token
  • resources (opsional): Array izin sumber daya untuk membatasi cakupan token. Setiap entri memiliki:
    • resource_type (wajib): Salah satu dari account, project, inbox, domain, billing
    • resource_id (wajib): ID sumber daya
    • access_level (wajib): 100 (admin) atau 10 (viewer)

get-api-token

Dapatkan token API berdasarkan ID. Hanya mengembalikan metadata — nilai token rahasia tidak dikembalikan di sini (hanya dari create-api-token / reset-api-token).

Parameter:

  • api_token_id (wajib): ID token API

reset-api-token

Reset (rotasi) token API berdasarkan ID. Respons mencakup nilai rahasia token baru — dikembalikan hanya pada panggilan ini, jadi segera simpan. Token sebelumnya dinonaktifkan.

Parameter:

  • api_token_id (wajib): ID token API yang akan direset

delete-api-token

Hapus token API secara permanen berdasarkan ID. Token tidak dapat lagi mengautentikasi setelah penghapusan.

Parameter:

  • api_token_id (wajib): ID token API yang akan dihapus

list-sub-accounts

Daftarkan sub-akun dalam organisasi. Memerlukan variabel env MAILTRAP_ORGANIZATION_ID dan izin manajemen sub-akun.

Parameter:

  • Tidak ada parameter yang diperlukan

create-sub-account

Buat sub-akun baru di bawah organisasi. Memerlukan variabel env MAILTRAP_ORGANIZATION_ID dan izin manajemen sub-akun.

Parameter:

  • name (wajib): Nama tampilan untuk sub-akun baru

Pengembangan

  1. Kloning repositori:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
  1. Instal dependensi:
npm install

Konfigurasi dengan Claude Desktop atau Cursor

[!TIP] Lihat lokasi file konfigurasi di bagian Setup.

Tambahkan konfigurasi berikut:

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

Jika Anda menggunakan asdf untuk mengelola Node.js, gunakan path absolut ke executable:

(contoh untuk 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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] Lihat lokasi file konfigurasi di bagian 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": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

Pengujian

Menjalankan alat terhadap Mailtrap sungguhan

Ada dua cara untuk menjalankan alat secara end-to-end terhadap akun Mailtrap sungguhan: UI browser MCP Inspector untuk eksplorasi interaktif, atau mode CLI-nya untuk panggilan sekali jalan dari shell.

Keduanya memerlukan bundle untuk dibangun terlebih dahulu:

npm run build

dan MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID diekspor di shell Anda (skrip mcp:cli meneruskan keduanya ke server yang dijalankan).

UI Browser

npm run dev

Inspector mencetak URL seperti http://localhost:6274. Buka, beralih ke tab Tools, pilih alat (mis. get-template), isi parameter sebagai JSON, dan tekan Run. Respons Mailtrap muncul di panel bawah.

CLI

Untuk panggilan sekali jalan tanpa UI, gunakan npm run mcp:cli. Berikan flag CLI Inspector setelah -- agar npm meneruskannya secara verbatim:

# 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 protected]

Menjalankan Server MCPB

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

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] Untuk pengembangan dengan MCP Inspector:

npm run dev:mcpb

Penanganan Error

Server ini menggunakan penanganan error terstruktur yang selaras dengan konvensi MCP:

  • VALIDATION_ERROR: Kegagalan validasi input
  • CONFIGURATION_ERROR: Konfigurasi hilang atau tidak valid
  • EXECUTION_ERROR: Error eksekusi runtime
  • TIMEOUT: Timeout operasi (default 30 detik)

Error mencakup pesan yang dapat ditindaklanjuti dan dicatat dalam bentuk terstruktur.

Keamanan

  • Input divalidasi melalui skema Zod
  • Variabel lingkungan ditangani dengan aman
  • Perlindungan timeout pada operasi (30 detik)
  • Detail sensitif disanitasi dalam output error

Pencatatan

Log JSON terstruktur dengan level: INFO, WARN, ERROR, DEBUG.

Aktifkan log debug dengan mengatur DEBUG=true.

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

Penting: Server menulis log ke stderr sehingga stdout tetap dicadangkan untuk frame JSON-RPC. Ini mencegah host mengalami error parsing JSON akibat log yang tercampur.

Contoh analisis log menggunakan 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")'

Pemecahan Masalah

Masalah umum:

  1. Token API hilang: pastikan MAILTRAP_API_TOKEN diatur
  2. Sandbox tidak berfungsi: berikan test_inbox_id dalam panggilan alat atau atur env MAILTRAP_TEST_INBOX_ID
  3. Error timeout: periksa konektivitas jaringan dan status API Mailtrap
  4. Error validasi: pastikan semua field wajib disediakan

Berkontribusi

Laporan bug dan pull request diterima di GitHub. Proyek ini dimaksudkan sebagai ruang yang aman dan ramah untuk kolaborasi, dan kontributor diharapkan mematuhi kode etik.

Lisensi

Paket ini tersedia sebagai sumber terbuka di bawah ketentuan Lisensi MIT.

Kode Etik

Setiap orang yang berinteraksi dalam basis kode, pelacak isu, ruang obrolan, dan milis proyek Mailtrap diharapkan mengikuti kode etik.