RMail MCP Server

1. Overview

The RMail® MCP Server is an enterprise-grade integration layer that exposes the RMail® by RPost secure communications platform as a set of structured tools consumable by AI agents. It implements the Model Context Protocol (MCP) specification over JSON-RPC 2.0, enabling large language models such as Claude and custom LLM agents to send Registered Email™ and Registered Text™ messages, query delivery status, and retrieve cryptographic Registered Receipts®, all programmatically without any need for coding expertise.

The server acts as an intermediary between AI agents and the RMail® REST API, translating natural-language-driven tool calls into authenticated HTTP requests and returning structured, agent-compatible JSON responses.

1.1 Purpose

• Allow AI agents to send, track, and audit secure email and SMS communications via RMail® without direct API access.
• Provide a secure, stateful session model that maintains Bearer access tokens across tool calls within a session.
• Expose a minimal, well-defined tool surface following MCP conventions.
• Handle attachment uploads transparently — agents provide file content; the server manages the upload lifecycle.

1.2 Compatibility

• Claude Desktop (Anthropic)
• Custom LLM agents using the MCP
• Any MCP-compliant client

2. Architecture

The server follows a single-process, tool-based architecture. All communication between the AI agent and the MCP server occurs over standard input/output (stdio) using the JSON-RPC 2.0 framing defined by the MCP specification. The server then makes outbound HTTPS calls to the RMail® REST API on behalf of the agent.

2.1 Communication Flow

2.2 Session State

Bearer access tokens are stored in-memory within the server process for the lifetime of the session. Credentials and tokens are never passed to the AI model layer and are never written to logs. Each new server process starts with a clean authentication state.

3. Project Structure

rmail-mcp-server/
├── src/
│   ├── index.js                    # MCP server entrypoint
│   └── tools/
│       ├── authenticateUser.js     # Tool: authenticate_user
│       ├── sendRegisteredEmail.js  # Tool: send_registered_email
│       ├── sendRegisteredText.js   # Tool: send_registered_text
│       ├── getEmailStatus.js       # Tool: get_email_status
│       └── getReceipt.js           # Tool: get_receipt
├── .env                            # Runtime credentials (not committed)
├── package.json
└── README.md

4. Requirements

5. Installation & Configuration

5.1 Install Dependencies

Navigate to the project root and install required Node.js dependencies:

npm install

5.2 Environment Variables

Create a .env file in the project root with the following variables. These credentials are loaded at runtime and are never exposed to the model layer.

RMAIL_BASE_URL=your_rmail_base_url
RMAIL_USERNAME=your@email.com
RMAIL_PASSWORD=your_password

WARNING: Never commit the .env file to source control. Add it to .gitignore.

5.3 Claude Desktop Configuration

To use the server with Claude Desktop, add the following block to claude_desktop_config.json, replacing placeholder values with your actual credentials and server path:

{
  "mcpServers": {
    "rmailbyrpost-mcp": {
      "command": "node",
      "args": [
        "C:/YourPathToServer/src/index.js"
      ],
      "env": {
        "RMAIL_BASE_URL": "your_base_url",
        "RMAIL_USERNAME": "YourUsername",
        "RMAIL_PASSWORD": "YourPassword"
      }
    }
  }
}

6. Tools Reference

The MCP server exposes five tools via the tools/call method. All tools return structured JSON responses compatible with Claude and other MCP clients.

6.1 authenticate_user

Authenticates the agent session against the RMail® API using credentials from the server's environment variables. Must be called before any other tool. On success, the Bearer token is stored in server memory and automatically attached to subsequent requests.

Input parameters

This tool takes no input parameters. Credentials are read from environment variables (RMAIL_USERNAME, RMAIL_PASSWORD) at runtime.

Response

{
  "authenticated": true,
  "tokenType": "bearer",
  "expiresIn": 86399,
  "userName": "your@email.com",
  "issued": "Thu, 01 Jan 2026 10:00:00 GMT",
  "expires": "Fri, 02 Jan 2026 09:59:59 GMT"
}

Note: The Bearer token itself is never included in the response returned to the agent.

6.2 send_registered_email

Sends an RMail® Registered Email™ message. By default, the message is sent Registered, Marked, and unencrypted. Optional features include encryption, Unmarked delivery, file attachments, and Large Mail.

Input parameters

Response

{
  "sent": true,
  "trackingId": "ABC123XYZ",
  "message": "Email sent successfully"
}

Note: The trackingId is used with get_email_status and get_receipt.

6.3 send_registered_text

Sends an RMail® Registered Text™ / Registered Email™ message where at least one recipient receives the message via SMS. Additional recipients can receive via email. For email-only messages, use send_registered_email instead. Recipients are provided as arrays of objects with per-recipient channel settings.

Note: SMS sending requires account enablement by your RPost® representative.

Input parameters

Recipient object fields

Response

{
  "sent": true,
  "trackingId": "DEF456UVW",
  "message": "Message sent successfully"
}

6.4 get_email_status

Retrieves the delivery and open status of a previously sent message. Returns per-recipient details including delivery timestamps and open events. Status data is available for up to 30 days after sending.

Input parameters

Response

{
  "trackingId": "ABC123XYZ",
  "senderName": "Jane Smith",
  "senderAddress": "jane@example.com",
  "sentDate": "2026-01-15T10:00:00Z",
  "overallStatus": "Delivered",
  "recipients": [
    {
      "address": "recipient@example.com",
      "recipientType": "To",
      "deliveryStatus": "Delivered",
      "deliveredDate": "2026-01-15T10:01:22Z",
      "openedDate": "2026-01-15T11:34:05Z",
      "deliveryDetail": "Delivered to recipient mail server"
    }
  ]
}

6.5 get_receipt

Retrieves the cryptographic Registered Receipt® for a previously sent message. Returns a base64-encoded .zip archive containing a FolderContents.txt manifest and one or more *Receipt_*.eml files.

Availability: The receipt is available only after 2 hours from sending or 20 minutes after all recipients open the message, and for up to 30 days after sending.

Receipt growth: The set of files inside the zip grows over time as recipients take actions. An OpenReceipt entry, for example, appears after a recipient opens the message. Calling this tool again for the same Tracking ID at a later time may return additional receipt files.

Input parameters

Response

{
  "trackingId": "ABC123XYZ",
  "fileName": "Receipt_ABC123XYZ.zip",
  "contentType": "application/zip",
  "encoding": "base64",
  "data": "<base64-encoded zip content>",
  "contents": {
    "manifest": "FolderContents.txt",
    "manifestParsed": true,
    "receiptCount": 2,
    "receipts": [
      { "type": "RegisteredReceipt", "recipient": null,
        "fileName": "RegisteredReceipt_ABC123XYZ.eml" },
      { "type": "OpenReceipt", "recipient": "recipient@example.com",
        "fileName": "OpenReceipt_ABC123XYZ.eml" }
    ]
  }
}

Note: Manifest format: each row in FolderContents.txt follows the pattern <ReceiptType>|<recipient-or-empty>|<filename>. The recipient field is empty for the transaction-level RegisteredReceipt and identifies the recipient for event-based receipts such as OpenReceipt. Each receipt can be verified at https://receipts.r1.rpost.net/Receipt-Authentication/<trackingId>.

7. Error Handling

All errors follow the JSON-RPC 2.0 error object format and are returned as structured MCP error responses. The server never throws unhandled exceptions to the agent.

Error response format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32010,
    "message": "RMail authentication misconfigured: missing environment variables"
  }
}

Error code ranges by tool

Common error causes

8. Security

Credentials and Bearer tokens are stored exclusively in process memory. They are never logged, written to disk, or passed to the AI model layer under any circumstances.

8.1 Security Properties

• API credentials (username and password) are loaded from environment variables at startup and never hardcoded.
• Bearer access tokens exist only in server process memory and are scoped to a single session.
• No credential or token is ever included in tool responses returned to the agent.
• All outbound communication to the RMail® API is made over HTTPS.
• The .env file must never be committed to version control.

8.2 Recommendations

• Use a secrets manager in production environments instead of a flat .env file.
• Rotate RMail® API credentials on a regular schedule.
• Restrict network egress from the host running the MCP server to only the RMail® API endpoint.
• Do not modify the server source code. For questions, contact integrations@rpost.com.

9. Typical Agent Workflows

Workflow A — Sending a Registered Email™

The standard flow for sending a tracked, legally provable email and later retrieving its receipt.

Workflow B — Sending a Registered Text™ (SMS)

This flow applies when at least one recipient should receive the message via SMS.