Add email-logs tools

Author: mklocek

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [Unreleased]
 
-* Add **get-sending-stats** tool: check delivery, bounce, open, click, and spam rates for a date range; optional breakdown by domain, category, email service provider, or date. Requires `MAILTRAP_ACCOUNT_ID`.
+* Add **list-email-logs** and **get-email-log-message** tools: query sent-mail delivery history with filters and pagination; inspect a single log by UUID (summary, event timeline, optional body via `include_content`).
+* Add **get-sending-stats** tool: check delivery, bounce, open, click, and spam rates for a date range; optional breakdown by domain, category, email service provider, or date.
 
 ## [0.1.0] - 2025-12-09
 

CLAUDE.md

@@ -5,16 +5,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Development Commands
 
 ### Build and Development
+
 - `npm run build` - Compile TypeScript to JavaScript in the `dist/` directory
 - `npm run dev` - Run the MCP server with the MCP Inspector for testing
 - `npm run prepublish` - Build the project and make the executable script executable
 
 ### Code Quality
+
 - `npm run lint` - Run both ESLint and TypeScript checks
 - `npm run lint:eslint` - Run ESLint for code style checking
 - `npm run lint:tsc` - Run TypeScript compiler for type checking
 
 ### Testing
+
 - `npm test` - Run all Jest tests
 - `npm run test:watch` - Run tests in watch mode during development
 - `npm run test:coverage` - Run tests with coverage reporting
@@ -24,59 +27,73 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 This is an MCP (Model Context Protocol) server that integrates with Mailtrap's email service. The architecture follows a modular pattern:
 
 ### Core Components
+
 - **src/index.ts**: Main MCP server entry point that registers all tools and handles the server lifecycle
 - **src/client.ts**: Mailtrap client configuration and initialization
 - **src/config/index.ts**: Server configuration constants
 
 ### Tool Architecture
+
 All tools follow a consistent pattern in the `src/tools/` directory:
-- Each tool has its own subdirectory (e.g., `sendEmail/`, `templates/`)
-- Tools export both their implementation function and Zod schema for validation
+
+- Each tool (or tool group) has its own subdirectory (e.g., `sendEmail/`, `templates/`, `emailLogs/`)
+- Tools export an **input schema** (JSON Schema–style object for MCP `inputSchema`) and a **handler** function
 - Template operations are grouped under `templates/` with individual files for each CRUD operation
+- **Runtime validation**: Handlers may validate input with Zod (see `stats/schema.ts` and `getSendingStats.ts`). Other tools use TypeScript types and ad-hoc checks; adding Zod validation in handlers is recommended for consistency
 
 ### Tool Structure Pattern
-```
-src/tools/{toolName}/
-├── index.ts          # Main tool export
-├── schema.ts         # Zod validation schema
-├── {toolName}.ts     # Tool implementation
-└── __tests__/        # Jest test files
-```
+
+- Single-tool dirs (e.g. `sendEmail/`, `stats/`): `index.ts`, `schema.ts` (or `schema.ts` + Zod in handler), implementation file(s), `__tests__/`
+- Multi-tool dirs (e.g. `templates/`, `sandbox/`, `emailLogs/`): `index.ts`, `schemas/*.ts` (one schema per tool), implementation file(s), `__tests__/`
+
+Schema files define a JSON Schema–shaped object for MCP; optional Zod schemas in the same or separate file can be used for runtime validation in the handler.
 
 ### Environment Variables Required
+
 - `MAILTRAP_API_TOKEN`: Required API token from Mailtrap
 - `DEFAULT_FROM_EMAIL`: Default sender email address
-- `MAILTRAP_ACCOUNT_ID`: Required for template management and sending stats (optional for send-email only)
+- `MAILTRAP_ACCOUNT_ID`: Required for almost all tools (templates, stats, email logs, sandbox list/show). Optional only for send-email and send-sandbox-email.
 - `MAILTRAP_TEST_INBOX_ID`: Required for sandbox tools - test inbox ID for sandbox mode operations
 
 ### Testing Setup
+
 - Uses Jest with TypeScript support via ts-jest
 - Test files are located in `__tests__/` directories within each tool
 - Environment variables are set up via `jest/setEnvVars.js`
 - Coverage reports exclude test files and type definitions
 
 ### Build Configuration
+
 - TypeScript compilation targets ES2022 with CommonJS modules
 - Separate build config (`tsconfig.build.json`) excludes test files from distribution
 - Output goes to `dist/` directory with proper executable permissions
 
 ### Available MCP Tools
 
 #### Transactional Email
-1. **send-email**: Send transactional emails through Mailtrap
+
+- **send-email**: Send transactional emails through Mailtrap.
+
+#### Email Logs
+
+- **list-email-logs**: List sent email logs (delivery history) with optional pagination and filters; use to debug delivery issues.
+- **get-email-log-message**: Get a single email log message by ID (UUID) to inspect delivery status and event history; optional `include_content` loads message body when available.
+
+#### Statistics
+
+- **get-sending-stats**: Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range; optionally break down by domain, category, email service provider, or date.
 
 #### Email Templates
-2. **create-template**: Create new email templates
-3. **list-templates**: List all email templates
-4. **update-template**: Update existing email templates
-5. **delete-template**: Delete email templates
+
+- **create-template**: Create new email templates.
+- **list-templates**: List all email templates.
+- **update-template**: Update existing email templates.
+- **delete-template**: Delete email templates.
 
 #### Sandbox Testing
-6. **send-sandbox-email**: Send email in sandbox mode to a test inbox
-7. **get-sandbox-messages**: Get list of messages from the sandbox test inbox
-8. **show-sandbox-email-message**: Show sandbox email message details and content from the sandbox test inbox
 
-#### Statistics
-9. **get-sending-stats**: Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range; optionally break down by domain, category, email service provider, or date. Requires `MAILTRAP_ACCOUNT_ID`.
+- **send-sandbox-email**: Send email in sandbox mode to a test inbox.
+- **get-sandbox-messages**: Get list of messages from the sandbox test inbox.
+- **show-sandbox-email-message**: Show sandbox email message details and content from the sandbox test inbox.
 
-Each tool uses Zod schemas for input validation and follows the MCP protocol for response formatting.
+Tools use input schemas (JSON Schema format) for MCP; handlers may validate input with Zod. Response format follows the MCP protocol.

README.md

@@ -4,7 +4,7 @@
 
 # MCP Mailtrap Server
 
-An MCP server that provides tools for sending transactional emails, managing email templates, checking sending statistics, and testing in sandbox via Mailtrap
+An MCP server that provides tools for sending and testing in sandbox via Mailtrap.
 
 ## Prerequisites
 
@@ -16,10 +16,11 @@ Before using this MCP server, you need to:
 4. Get your Account ID from [Mailtrap account management](https://mailtrap.io/account-management)
 
 **Required Environment Variables:**
+
 - `MAILTRAP_API_TOKEN` - Required for all functionality
 - `DEFAULT_FROM_EMAIL` - Required for all email sending operations
-- `MAILTRAP_ACCOUNT_ID` - Required for template management and sending statistics
-- `MAILTRAP_TEST_INBOX_ID` - **Only** required for sandbox email functionality
+- `MAILTRAP_ACCOUNT_ID` - Required for almost all tools (templates, stats, email logs, sandbox list/show). Optional only for send-email and send-sandbox-email.
+- `MAILTRAP_TEST_INBOX_ID` - Required for sandbox tools (send, list messages, show message)
 
 ## Quick Install
 
@@ -42,7 +43,9 @@ npx @smithery/cli install mailtrap
 
 
 ## Setup
+
 ### Claude Desktop
+
 Use MCPB to install the Mailtrap server. You can find those files in [Releases](https://github.com/mailtrap/mailtrap-mcp/releases). <br>Download .MCPB file and open it. If you have Claude Desktop - it will open it and suggest to configure.
 
 ### Claude Desktop or Cursor
@@ -153,12 +156,24 @@ This creates `mailtrap-mcp.mcpb` using the repository `manifest.json` and built
 
 Once configured, you can ask agent to send emails and manage templates, for example:
 
-**Email Operations:**
+**Email Sending Operations:**
 
 - "Send an email to john.doe@example.com with the subject 'Meeting Tomorrow' and a friendly reminder about our upcoming meeting."
 - "Email sarah@example.com about the project update, and CC the team at team@example.com"
 - "Send a sandbox email to test@example.com with subject 'Test Template' to preview how our welcome email looks"
 
+**Email Logs (debug delivery):**
+
+- "List my recent sent email logs"
+- "Show email logs for emails sent to user@example.com"
+- "Get the email log message for ID abc-123-uuid to check delivery status"
+
+**Sending Statistics:**
+
+- "Get sending stats for January 2025"
+- "Show delivery rates broken down by domain for last month"
+- "What are my email stats by category from 2025-01-01 to 2025-01-31?"
+
 **Sandbox Operations:**
 
 - "Get all messages from my sandbox inbox"
@@ -173,12 +188,6 @@ Once configured, you can ask agent to send emails and manage templates, for exam
 - "Update the template with ID 12345 to change the subject to 'Updated Welcome Message'"
 - "Delete the template with ID 67890"
 
-**Statistics:**
-
-- "Get sending stats for January 2025"
-- "Show delivery rates broken down by domain for last month"
-- "What are my email stats by category from 2025-01-01 to 2025-01-31?"
-
 ## Available Tools
 
 ### send-email
@@ -196,47 +205,53 @@ Sends a transactional email through Mailtrap.
 - `bcc` (optional): Array of BCC recipient email addresses
 - `category` (required): Email category for tracking and analytics
 
-### send-sandbox-email
+### list-email-logs
 
-Sends an email to your Mailtrap test inbox for development and testing purposes. This is perfect for testing email templates without sending emails to real recipients.
+Lists sent email logs (delivery history) with optional pagination and filters. Use to debug delivery issues from the IDE.
 
 **Parameters:**
 
-- `to` (required): Email address(es) of the recipient(s) - can be a single email or array of emails (will be delivered to your test inbox)
-- `subject` (required): Email subject line
-- `from` (optional): Email address of the sender, if not provided "DEFAULT_FROM_EMAIL" will be used
-- `text` (optional): Email body text, required if "html" is empty
-- `html` (optional): HTML version of the email body, required if "text" is empty
-- `cc` (optional): Array of CC recipient email addresses
-- `bcc` (optional): Array of BCC recipient email addresses
-- `category` (optional): Email category for tracking
-
-> [!NOTE]
-> The `MAILTRAP_TEST_INBOX_ID` environment variable must be configured for sandbox emails to work. This variable is **only** required for sandbox functionality and is not needed for regular transactional emails or template management.
-
-### get-sandbox-messages
-
-Retrieves a list of messages from your Mailtrap test inbox. Useful for checking what emails have been received in your sandbox during testing.
+- `search_after` (optional): Pagination cursor from the previous response's `next_page_cursor`
+- `sent_after` (optional): ISO 8601 date/time; only logs sent after this time
+- `sent_before` (optional): ISO 8601 date/time; only logs sent before this time
+- `from_email` (optional): Filter by sender email; use with `from_operator` (default: ci_equal)
+- `to_email` (optional): Filter by recipient email; use with `to_operator` (default: ci_equal)
+- `status` (optional): Filter by delivery status: delivered, not_delivered, enqueued, opted_out; use with `status_operator` (default: equal)
+- `subject` (optional): Filter by email subject; use with `subject_operator` (default: ci_contain). Use `subject_operator`: empty/not_empty to filter by presence of subject.
+- `sending_domain_id` (optional): Filter by sending domain ID (number); use with `sending_domain_id_operator` (default: equal)
+- `sending_stream` (optional): Filter by stream: transactional or bulk; use with `sending_stream_operator` (default: equal)
+- `events` (optional): Filter by event type(s): delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; use with `events_operator` (include_event / not_include_event)
+- `clicks_count` / `opens_count` (optional): Filter by click/open count; use with `*_operator`: equal, greater_than, less_than
+- `client_ip` / `sending_ip` (optional): Filter by IP; use with `*_operator`: equal, not_equal, contain, not_contain
+- `email_service_provider_response` (optional): Filter by provider response text; use with `*_operator` (ci_contain, etc.)
+- `email_service_provider` (optional): Filter by provider (exact); use with `*_operator`: equal, not_equal
+- `recipient_mx` (optional): Filter by recipient MX; use with `recipient_mx_operator` (ci_contain, etc.)
+- `category` (optional): Filter by email category; use with `category_operator`: equal, not_equal
+
+All parameters are optional.
+
+### get-email-log-message
+
+Gets a single email log message by ID (UUID): a readable summary (from, to, subject, sent time, status, category, stream, engagement, delivery context), then detailed event history. Optionally, with `include_content: true`, you can also load and show the message body (HTML and plain text) when Mailtrap exposes a raw message URL.
 
 **Parameters:**
 
-- `page` (optional): Page number for pagination (minimum: 1)
-- `last_id` (optional): Pagination using last message ID. Returns messages after the specified message ID (minimum: 1)
-- `search` (optional): Search query to filter messages
-
-> [!NOTE]
-> All parameters are optional. If none are provided, the first page of messages from the inbox will be returned. Use page for traditional pagination, last_id for cursor-based pagination, or search to filter messages by content.
+- `message_id` (required): UUID of the email log message (from send response or list-email-logs). Use `list-email-logs` to find message IDs.
+- `include_content` (optional): When `true`, fetches the raw EML (if `raw_message_url` is available) and appends parsed HTML and plain-text body sections, similar to show-sandbox-email-message.
 
-### show-sandbox-email-message
+### get-sending-stats
 
-Shows detailed information and content of a specific email message from your Mailtrap test inbox, including HTML and text body content.
+Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range. Optionally break down by domain, category, email service provider, or date. Check delivery rates without leaving the editor.
 
 **Parameters:**
 
-- `message_id` (required): ID of the sandbox email message to retrieve
-
-> [!NOTE]
-> Use `get-sandbox-messages` first to get the list of messages and their IDs, then use this tool to view the full content of a specific message.
+- `start_date` (required): Start date for the stats range (YYYY-MM-DD)
+- `end_date` (required): End date for the stats range (YYYY-MM-DD)
+- `breakdown` (optional): How to break down the stats: `aggregated` (default), `by_domain`, `by_category`, `by_email_service_provider`, or `by_date`
+- `sending_domain_ids` (optional): Limit results to these sending domain IDs (array of integers)
+- `sending_streams` (optional): Limit to `transactional` and/or `bulk` (array of strings)
+- `categories` (optional): Limit to these email categories (array of strings)
+- `email_service_providers` (optional): Limit to these providers, e.g. Google, Yahoo, Outlook (array of strings)
 
 ### create-template
 
@@ -282,22 +297,48 @@ Deletes an existing email template.
 
 - `template_id` (required): ID of the template to delete
 
-### get-sending-stats
+### send-sandbox-email
 
-Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range. Optionally break down by domain, category, email service provider, or date. Check delivery rates without leaving the editor.
+Sends an email to your Mailtrap test inbox for development and testing purposes. This is perfect for testing email templates without sending emails to real recipients.
 
 **Parameters:**
 
-- `start_date` (required): Start date for the stats range (YYYY-MM-DD)
-- `end_date` (required): End date for the stats range (YYYY-MM-DD)
-- `breakdown` (optional): How to break down the stats: `aggregated` (default), `by_domain`, `by_category`, `by_email_service_provider`, or `by_date`
-- `sending_domain_ids` (optional): Limit results to these sending domain IDs (array of integers)
-- `sending_streams` (optional): Limit to `transactional` and/or `bulk` (array of strings)
-- `categories` (optional): Limit to these email categories (array of strings)
-- `email_service_providers` (optional): Limit to these providers, e.g. Google, Yahoo, Outlook (array of strings)
+- `to` (required): Email address(es) of the recipient(s) - can be a single email or array of emails (will be delivered to your test inbox)
+- `subject` (required): Email subject line
+- `from` (optional): Email address of the sender, if not provided "DEFAULT_FROM_EMAIL" will be used
+- `text` (optional): Email body text, required if "html" is empty
+- `html` (optional): HTML version of the email body, required if "text" is empty
+- `cc` (optional): Array of CC recipient email addresses
+- `bcc` (optional): Array of BCC recipient email addresses
+- `category` (optional): Email category for tracking
 
 > [!NOTE]
-> `MAILTRAP_ACCOUNT_ID` must be set for this tool to work.
+> The `MAILTRAP_TEST_INBOX_ID` environment variable must be configured for sandbox emails to work. This variable is **only** required for sandbox functionality and is not needed for regular transactional emails or template management.
+
+### get-sandbox-messages
+
+Retrieves a list of messages from your Mailtrap test inbox. Useful for checking what emails have been received in your sandbox during testing.
+
+**Parameters:**
+
+- `page` (optional): Page number for pagination (minimum: 1)
+- `last_id` (optional): Pagination using last message ID. Returns messages after the specified message ID (minimum: 1)
+- `search` (optional): Search query to filter messages
+
+> [!NOTE]
+> All parameters are optional. If none are provided, the first page of messages from the inbox will be returned. Use page for traditional pagination, last_id for cursor-based pagination, or search to filter messages by content.
+
+### show-sandbox-email-message
+
+Shows detailed information and content of a specific email message from your Mailtrap test inbox, including HTML and text body content.
+
+**Parameters:**
+
+- `message_id` (required): ID of the sandbox email message to retrieve
+
+> [!NOTE]
+> Use `get-sandbox-messages` first to get the list of messages and their IDs, then use this tool to view the full content of a specific message.
+
 
 ## Development