Documentation

Comprehensive guide to integrating Mockmail's REST API and MCP Server into your workflow

MCP Server

Overview

The Model Context Protocol (MCP) server allows AI tools and coding agents, such as Claude Code, to access your Mockmail inboxes and emails.

This is particularly useful for AI assistants that need to verify and test emails automatically. Configure your application runtime to use your Mockmail virtual SMTP server and allow your coding agent to send emails from your development environment.

Mockmail safely captures all outgoing emails. Your AI coding agent can then autonomously inspect, verify, and debug those emails through the Mockmail MCP server.

Installation

To connect any AI coding agent to the Mockmail MCP Server, you first need to generate an API key.

1. Generate an API Key

Log in to your Mockmail account and navigate to API Keys. Click New API Key and give it a descriptive name. Copy the token immediately, as it will not be displayed again.

Important: Store your API token securely. It provides full access to your inboxes and emails. Never commit tokens to version control.

2. Connect Claude Code

There are several ways to add the Mockmail MCP server to your Claude Code installation.

Option 1: Using the CLI (Recommended)

The easiest and fastest way is to open a terminal and run the following command:

claude mcp add --transport http mockmail https://mockmail.io/mcp/mockmail \
  --header "Authorization: Bearer your-token"

Replace your-token with your API token from the Dashboard.

Option 2: Manual Configuration in .claude.json

Alternatively, you can add the MCP server manually to your personal Claude settings file ~/.claude.json:

{
  "mcpServers": {
    "mockmail": {
      "type": "http",
      "url": "https://mockmail.io/mcp/mockmail",
      "headers": {
        "Authorization": "Bearer ${MOCKMAIL_API_KEY}"
      }
    }
  }
}

Make sure to set your personal Mockmail API key as an environment variable named MOCKMAIL_API_KEY.

3. Project-Specific Configuration

The previous methods enable the MCP server globally for all your projects. If you want to enable the MCP server only for a single project, create a .mcp.json file in your project directory with the following contents:

{
  "mcpServers": {
    "mockmail": {
      "type": "http",
      "url": "https://mockmail.io/mcp/mockmail",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Note: When using a project-specific MCP configuration, Claude will ask you to approve the MCP server at the start of each session.

Available Tools

The MCP server provides three tools:

list-inboxes

Lists all inboxes accessible to the authenticated user.

Parameters

No parameters required

Example Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list-inboxes",
    "arguments": {}
  },
  "id": 3
}

Example Response

{
  "success": true,
  "count": 2,
  "inboxes": [
    {
      "id": 1,
      "name": "Development Inbox",
      "username": "inbox_abc123",
      "email_count": 42,
      "email_limit": 100,
      "webhook_endpoint": "https://example.com/webhook",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-07T14:22:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates whether the request was successful
`count`	integer	Number of inboxes returned
`inboxes`	array	Array of inbox objects
`inboxes[].id`	integer	Unique inbox ID
`inboxes[].name`	string	Display name of the inbox
`inboxes[].username`	string	SMTP/IMAP username for the inbox
`inboxes[].email_count`	integer	Current number of emails in the inbox
`inboxes[].email_limit`	integer	Maximum number of emails allowed

list-emails

Lists emails from a specific inbox with optional pagination and search.

Parameters

Parameter	Type	Required	Description
`inbox_id`	integer	Yes	The ID of the inbox to retrieve emails from
`offset`	integer	No	Number of emails to skip (for pagination). Default: 0
`limit`	integer	No	Maximum number of emails to retrieve (1-100). Default: 10
`query`	string	No	Search query to filter emails by subject

Example Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list-emails",
    "arguments": {
      "inbox_id": 1,
      "limit": 5,
      "offset": 0,
      "query": "password reset"
    }
  },
  "id": 4
}

Example Response

{
  "success": true,
  "inbox_id": 1,
  "total": 42,
  "offset": 0,
  "limit": 5,
  "count": 5,
  "emails": [
    {
      "id": 123,
      "subject": "Password Reset Request",
      "excerpt": "Click the link below to reset your password...",
      "date": "2024-03-07T10:30:00Z",
      "from_name": "Support Team",
      "from_address": "support@example.com",
      "to_address": "user@test.com",
      "read": false,
      "attachments": []
    }
  ]
}

get-email-content

Retrieves the full content of a specific email in HTML or plain text format.

Parameters

Parameter	Type	Required	Description
`inbox_id`	integer	Yes	The ID of the inbox containing the email
`email_id`	integer	Yes	The ID of the email to retrieve
`format`	string	No	Content format: "html" or "plain". Default: "html"

Example Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get-email-content",
    "arguments": {
      "inbox_id": 1,
      "email_id": 123,
      "format": "html"
    }
  },
  "id": 5
}

Example Response

{
  "success": true,
  "email": {
    "id": 123,
    "subject": "Password Reset Request",
    "from_name": "Support Team",
    "from_address": "support@example.com",
    "to_address": "user@test.com",
    "date": "2024-03-07T10:30:00Z",
    "read": false,
    "format": "html",
    "content": "<html><body><p>Click the link...</p></body></html>",
    "inbox": {
      "id": 1,
      "name": "Development Inbox"
    },
    "attachments": [
      {
        "id": 456,
        "cid": null,
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 45678
      }
    ]
  }
}

REST API

Overview

The REST API provides HTTP endpoints for accessing your Mockmail data. All endpoints are prefixed with /api/v1 and require authentication via Bearer token.

Base URL

https://mockmail.io/api/v1

Response Format

All API responses are in JSON format with the following structure:

{
  "success": true,
  "data": { ... }
}

Error Responses

Error responses contain an error message:

{
  "success": false,
  "error": "Error description"
}

HTTP Status Codes

Code	Meaning
`200`	Success
`401`	Unauthorized - Invalid or missing API token
`403`	Forbidden - No permission for this resource
`404`	Not Found - Resource does not exist
`422`	Validation Error - Invalid input parameters

Generate API Keys

All API requests require authentication using Laravel Sanctum API tokens.

Create a Token

Log in to your Mockmail account at /app
Navigate to Settings → API Keys
Click "Create New API Key"
Give your token a descriptive name (e.g., "Production Integration")
Copy the token immediately - it will only be shown once

Important: Store your API token securely. It provides full access to your inboxes and emails. Never commit tokens to version control.

Use the Token

Include your token in the Authorization header of all requests:

Authorization: Bearer YOUR_API_TOKEN_HERE

API Endpoints

GET /api/v1/inboxes

Retrieves all inboxes accessible to the authenticated user.

Request

GET /api/v1/inboxes HTTP/1.1
Host: localhost:8000
Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Development Inbox",
      "email_count": 42,
      "email_limit": 100,
      "username": "inbox_abc123",
      "password": "secure_password",
      "email_username": "custom@mockmail.io",
      "enable_email_username": true,
      "webhook_endpoint": "https://example.com/webhook",
      "enable_webhook": true,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-03-07T14:22:00.000000Z"
    },
    {
      "id": 2,
      "name": "Staging Inbox",
      "email_count": 15,
      "email_limit": 50,
      "username": "inbox_xyz789",
      "password": "another_password",
      "email_username": null,
      "enable_email_username": false,
      "webhook_endpoint": null,
      "enable_webhook": false,
      "created_at": "2024-02-01T08:15:00.000000Z",
      "updated_at": "2024-03-05T11:45:00.000000Z"
    }
  ]
}

cURL Example

curl -X GET https://mockmail.io/api/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"

Response Fields

Field	Type	Description
`id`	integer	Unique inbox ID
`name`	string	Display name of the inbox
`email_count`	integer	Current number of emails in the inbox
`email_limit`	integer	Maximum number of emails allowed in the inbox
`username`	string	SMTP/IMAP username for this inbox
`password`	string	SMTP/IMAP password for this inbox
`email_username`	string\|null	Custom email username if enabled
`enable_email_username`	boolean	Whether custom email username is enabled
`webhook_endpoint`	string\|null	Webhook URL for email notifications
`enable_webhook`	boolean	Whether webhook notifications are enabled
`created_at`	string	ISO 8601 timestamp when the inbox was created
`updated_at`	string	ISO 8601 timestamp when the inbox was last updated

GET /api/v1/inboxes/{id}/emails

Retrieves all emails from a specific inbox with optional pagination and search.

URL Parameters

Parameter	Type	Description
`id`	integer	The ID of the inbox to retrieve emails from

Query Parameters

Parameter	Type	Required	Description
`offset`	integer	No	Number of emails to skip (for pagination). Default: 0
`limit`	integer	No	Maximum number of emails to retrieve (1-100). Default: 10
`query`	string	No	Search query to filter emails by subject

Request

GET /api/v1/inboxes/1/emails?limit=5&offset=0&query=password%20reset HTTP/1.1
Host: localhost:8000
Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json

Response

{
  "success": true,
  "data": {
    "inbox_id": 1,
    "total": 42,
    "offset": 0,
    "limit": 5,
    "count": 5,
    "emails": [
      {
        "id": 123,
        "subject": "Password Reset Request",
        "date": "2024-03-07T10:30:00Z",
        "from_name": "Support Team",
        "from_address": "support@example.com",
        "to_address": "user@test.com"
      }
    ]
  }
}

cURL Example

curl -X GET "https://mockmail.io/api/v1/inboxes/1/emails?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"

Response Fields

Field	Type	Description
`inbox_id`	integer	ID of the inbox the emails belong to
`total`	integer	Total number of emails available in the inbox (matching search query if provided)
`offset`	integer	Pagination offset used for the query
`limit`	integer	Maximum number of emails requested
`count`	integer	Number of emails returned in this response
`emails`	array	Array of email objects
`emails[].id`	integer	Unique email ID
`emails[].subject`	string	Email subject
`emails[].date`	string	ISO 8601 timestamp when the email was received
`emails[].from_name`	string	Sender display name
`emails[].from_address`	string	Sender email address
`emails[].to_address`	string	Recipient email address

GET /api/v1/emails/{id}

Retrieve a single email with all its details, including HTML/plain text content and attachments.

Path Parameters

Parameter	Type	Description
`id`	integer	The ID of the email to retrieve

Request Example

GET /api/v1/emails/123 HTTP/1.1
Host: mockmail.io
Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json

Response

{
  "success": true,
  "data": {
    "id": 123,
    "subject": "Password Reset Request",
    "date": "2024-03-15T14:30:00.000000Z",
    "from_name": "Support Team",
    "from_address": "support@example.com",
    "to_address": "inbox_abc123@mockmail.io",
    "inbox_id": 1,
    "html": "<html><body><p>Click here to reset your password</p></body></html>",
    "text": "Click here to reset your password",
    "attachments": [
      {
        "id": 45,
        "filename": "logo.png",
        "content_type": "image/png",
        "size": 15234,
        "cid": "logo@example.com"
      }
    ]
  }
}

cURL Example

curl -X GET "https://mockmail.io/api/v1/emails/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Accept: application/json"

Response Fields

Field	Type	Description
`id`	integer	Unique email ID
`subject`	string	Email subject
`date`	string	ISO 8601 timestamp when the email was received
`from_name`	string	Sender display name
`from_address`	string	Sender email address
`to_address`	string	Recipient email address
`inbox_id`	integer	ID of the inbox this email belongs to
`html`	string\|null	HTML content of the email (if available)
`text`	string\|null	Plain text content of the email (if available)
`attachments`	array	Array of attachment objects
`attachments[].id`	integer	Unique attachment ID
`attachments[].filename`	string	Name of the attachment file
`attachments[].content_type`	string	MIME type of the attachment (e.g., "image/png", "application/pdf")
`attachments[].size`	integer	Size of the attachment in bytes
`attachments[].cid`	string	Content-ID for inline attachments (used in HTML emails)

Error Responses

Status Code	Description
`401`	Unauthorized - Invalid or missing API token
`403`	Forbidden - You don't have permission to access this email
`404`	Not Found - Email does not exist