# inxmail-mcp

[![CI](https://github.com/shahabazdev/inxmail-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shahabazdev/inxmail-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/inxmail-mcp)](https://www.npmjs.com/package/inxmail-mcp)
[![npm downloads](https://img.shields.io/npm/dm/inxmail-mcp)](https://www.npmjs.com/package/inxmail-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![Node.js](https://img.shields.io/node/v/inxmail-mcp)](https://nodejs.org)
[![Glama](https://glama.ai/mcp/servers/shahabazdev/inxmail-mcp/badges/score.svg)](https://glama.ai/mcp/servers/shahabazdev/inxmail-mcp)
[![Awesome MCP Servers](https://img.shields.io/badge/Awesome%20MCP-listed-brightgreen)](https://github.com/punkpeye/awesome-mcp-servers)

MCP server for the [Inxmail Commerce Transactional API](https://help.inxmail-commerce.com/inxmail-commerce-api.html). Manage events, sendings, bounces, blocklist, blacklist, reactions, and delivery tracking — directly from Claude.

## Quick Start

### 1. Install

```bash
npm install -g inxmail-mcp
# or use npx (no install needed)
```

### 2. Get API Credentials

In your Inxmail Commerce admin panel, create an API key under **API Login Data**. You'll get:
- **API Key ID** (username)
- **API Secret** (password)

Your instance name is the subdomain from your Inxmail Commerce API URL:
- `https://your-instance.api.inxmail-commerce.com/` -> instance = `your-instance`

### 3. Configure for Claude Code

```bash
claude mcp add inxmail-mcp -e INXMAIL_INSTANCE=your-instance -e INXMAIL_API_KEY_ID=your-key-id -e INXMAIL_API_SECRET=your-secret -- npx -y inxmail-mcp
```

Or from source:

```bash
claude mcp add inxmail-mcp -e INXMAIL_INSTANCE=your-instance -e INXMAIL_API_KEY_ID=your-key-id -e INXMAIL_API_SECRET=your-secret -- node /path/to/inxmail-mcp/build/index.js
```

### 4. Configure for Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "inxmail": {
      "command": "npx",
      "args": ["-y", "inxmail-mcp"],
      "env": {
        "INXMAIL_INSTANCE": "your-instance",
        "INXMAIL_API_KEY_ID": "your-key-id",
        "INXMAIL_API_SECRET": "your-secret"
      }
    }
  }
}
```

## Available Tools

### Core Use Cases

| Tool | Description |
|------|-------------|
| `check_email_delivery` | Check delivery status for an email — sendings, bounces, reactions, and block status |
| `check_email_blocked` | Check if an email is blocked (blocklist hard bounces + blacklist explicit blocks) |
| `get_server_info` | Get API entry point with links to all available resources |

### Events

| Tool | Description |
|------|-------------|
| `trigger_event` | Trigger a transactional email event |
| `get_event_state` | Get the state/result of a triggered event by transaction ID |
| `list_event_types` | List all configured event types |
| `get_event_type` | Get a single event type by ID |

### Sendings

| Tool | Description |
|------|-------------|
| `list_sendings` | List sent transaction emails with filters |
| `get_sending` | Get details of a specific sending by ID |

### Reactions & Tracking

| Tool | Description |
|------|-------------|
| `list_reactions` | List recipient reactions (opens and clicks) |
| `list_deliveries` | List delivery status information |

### Bounces & Complaints

| Tool | Description |
|------|-------------|
| `list_bounces` | List bounced transaction emails |
| `list_complaints` | List feedback loop complaints |

### Blocklist (Hard Bounces)

| Tool | Description |
|------|-------------|
| `list_blocklist` | List hard-bounce blocked email addresses |
| `get_blocklist_entry` | Check if a specific email is on the blocklist |
| `remove_from_blocklist` | Remove an email from the blocklist |

### Blacklist (Explicit Blocks)

| Tool | Description |
|------|-------------|
| `list_blacklist` | List explicitly blacklisted email addresses |
| `get_blacklist_entry` | Check if a specific email is on the blacklist |
| `add_to_blacklist` | Add an email address to the blacklist |
| `remove_from_blacklist` | Remove an email from the blacklist |

### Mail Relay

| Tool | Description |
|------|-------------|
| `list_relay_sendings` | List mail relay sendings |
| `get_relay_sending` | Get details of a specific mail relay sending |
| `list_relay_reactions` | List mail relay reactions (opens, clicks) |
| `list_relay_bounces` | List mail relay bounces |
| `list_relay_complaints` | List mail relay complaints |

### Raw Mail

| Tool | Description |
|------|-------------|
| `send_raw_mail` | Send a complete RFC 5322 email (Base64-encoded) |

### Error Logs

| Tool | Description |
|------|-------------|
| `list_error_logs` | List error log entries |
| `get_error_log` | Get a single error log entry by ID |
| `mark_error_log_read` | Mark an error log entry as read |

## Example Prompts

```
"Is test@example.com blocked or blacklisted?"

"Check the delivery status for user@example.com"

"List all bounces from last week"

"Trigger a welcome email event for new-user@example.com"

"Show me all event types configured in the system"

"List recent complaints from the last 30 days"
```

## Development

```bash
git clone https://github.com/shahabazdev/inxmail-mcp.git
cd inxmail-mcp
npm install
npm run build
```

## Testing

```bash
npm test          # run all tests
npx vitest        # run in watch mode
```

Runs unit tests with [Vitest](https://vitest.dev/) covering:
- API client (auth, request methods, query params, pagination, error handling)
- Tool registration (all 29 tools registered, no duplicates)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `INXMAIL_INSTANCE` | Yes | Instance subdomain (e.g. `your-instance`) |
| `INXMAIL_API_KEY_ID` | Yes | API Key ID |
| `INXMAIL_API_SECRET` | Yes | API Secret |

## License

MIT