Spotler Sendpro / Flowmailer Mcp Server

Spotler SendPro / FlowMailer MCP Server

Unofficial Model Context Protocol server for the Spotler SendPro API, formerly known as FlowMailer.

This project is not affiliated with, endorsed by, or maintained by Spotler. It is a community MCP server for teams that need controlled AI-agent access to SendPro account data and, when explicitly enabled, SendPro message operations.

What It Does

• Connects to SendPro over OAuth2 client credentials.
• Exposes SendPro operations as MCP tools over stdio.
• Defaults to read-only mode.
• Blocks mutating SendPro requests when read-only mode is enabled.
• Supports current SendPro naming plus legacy FlowMailer environment variables.
• Includes MCP Registry metadata in server.json.

Install

From npm:

npx -y sendpro-flowmailer-mcp

Directly from GitHub:

npx -y github:Mestika/sendpro-flowmailer-mcp

Local development:

git clone https://github.com/Mestika/sendpro-flowmailer-mcp.git
cd sendpro-flowmailer-mcp
npm install
npm run build
node dist/index.js

Configuration

Set credentials through your MCP client config, shell environment, or a local .env file.

Variable	Required	Default	Description
SENDPRO_ACCOUNT_ID	Yes		SendPro account id.
SENDPRO_CLIENT_ID	Yes		OAuth client id.
SENDPRO_CLIENT_SECRET	Yes		OAuth client secret.
SENDPRO_READ_ONLY	No	true	Safe-mode flag. When true, only SendPro read requests are allowed.
READ_ONLY	No		Generic override for SENDPRO_READ_ONLY; useful for shared MCP config conventions.
SENDPRO_API_BASE_URL	No	https://api.flowmailer.net	SendPro API base URL.
SENDPRO_AUTH_BASE_URL	No	https://login.flowmailer.net	OAuth base URL.
SENDPRO_API_MEDIA_TYPE	No	application/vnd.flowmailer.v1.12+json	SendPro vendor media type.

Legacy aliases are supported:

Current	Spotler alias	Legacy FlowMailer alias
SENDPRO_ACCOUNT_ID	SPOTLER_SENDPRO_ACCOUNT_ID	FLOWMAILER_ACCOUNT_ID
SENDPRO_CLIENT_ID	SPOTLER_SENDPRO_CLIENT_ID	FLOWMAILER_CLIENT_ID
SENDPRO_CLIENT_SECRET	SPOTLER_SENDPRO_CLIENT_SECRET	FLOWMAILER_CLIENT_SECRET
SENDPRO_READ_ONLY	SPOTLER_SENDPRO_READ_ONLY	FLOWMAILER_READ_ONLY

Precedence is: READ_ONLY, then SENDPRO_*, then SPOTLER_SENDPRO_*, then FLOWMAILER_*.

Creating SendPro API Credentials

SendPro uses OAuth2 client credentials. You need three values:

• account id
• client id
• client secret

The public SendPro API docs state that the API uses OAuth2 client credentials, that the access token endpoint is https://login.flowmailer.net/oauth/token, and that the client_id, client_secret, grant_type=client_credentials, and optional scope=api form values are used to request a token. The same docs also expose source-system credential endpoints under /{account_id}/sources/{source_id}/users, including endpoints to list, create, get, update, and delete source credentials.

In the SendPro dashboard, the exact labels can vary by account, but the usual path is:

1. Sign in to Spotler SendPro.
2. Go to Setup.
3. Open Sources or Source systems.
4. Select the source system that should be used for API access, or create a dedicated source for MCP/automation usage.
5. Open the source credentials/users section.
6. Create new credentials with a clear description such as MCP read-only.
7. Copy the generated client id and client secret, and store them in your MCP client environment.
8. Use the SendPro account id from your account URL, dashboard context, or API settings as SENDPRO_ACCOUNT_ID.

For AI-agent usage, prefer credentials that are limited to the minimum access needed. Keep this MCP server in read-only mode unless you explicitly need submit, simulate, or resend operations.

Official references:

• SendPro API authentication
• POST /oauth/token
• Source credential endpoints
• Spotler SendPro Help Center

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.sendpro_flowmailer]
command = "npx"
args = ["-y", "sendpro-flowmailer-mcp"]
startup_timeout_sec = 20.0

[mcp_servers.sendpro_flowmailer.env]
SENDPRO_ACCOUNT_ID = "your-account-id"
SENDPRO_CLIENT_ID = "your-client-id"
SENDPRO_CLIENT_SECRET = "your-client-secret"
SENDPRO_READ_ONLY = "true"

To run directly from GitHub:

[mcp_servers.sendpro_flowmailer]
command = "npx"
args = ["-y", "github:Mestika/sendpro-flowmailer-mcp"]
startup_timeout_sec = 20.0

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "sendpro-flowmailer": {
      "command": "npx",
      "args": ["-y", "sendpro-flowmailer-mcp"],
      "env": {
        "SENDPRO_ACCOUNT_ID": "your-account-id",
        "SENDPRO_CLIENT_ID": "your-client-id",
        "SENDPRO_CLIENT_SECRET": "your-client-secret",
        "SENDPRO_READ_ONLY": "true"
      }
    }
  }
}

Read-Only Mode

SENDPRO_READ_ONLY defaults to true.

When read-only mode is enabled:

• MCP schemas only allow GET for the generic request tool.
• Mutating helper tools are not registered.
• The low-level client rejects POST, PUT, PATCH, and DELETE SendPro API requests before requesting an OAuth token.

OAuth itself still uses POST https://login.flowmailer.net/oauth/token, because SendPro requires OAuth2 client credentials before any resource can be read. The read-only guard applies to SendPro API resource calls against the configured API base URL.

Tools

Read tools:

Tool	Description
flowmailer_request	Generic relative SendPro API request. In read-only mode, only GET is accepted.
flowmailer_endpoint_catalog	Lists SendPro endpoints known by this server.
flowmailer_list_messages	Lists messages using SendPro reference-range paging.
flowmailer_get_message	Gets one message by id.
flowmailer_get_message_archive	Gets archived content metadata for a message.
flowmailer_get_message_error_archive	Gets archived error content for a message.
flowmailer_get_recipient	Gets recipient information.
flowmailer_list_resource	Lists common resources such as flows, templates, sender domains, sources, and stats.

Write tools, only when SENDPRO_READ_ONLY=false:

Tool	Description
flowmailer_submit_message	Submits an email or SMS message.
flowmailer_simulate_message	Simulates an email or SMS message.
flowmailer_resend_message	Resends a message by id.

The tool names currently retain the FlowMailer prefix because the public SendPro API and media types still use FlowMailer naming in several places. Package names and documentation use both SendPro and FlowMailer for discoverability.

Examples

List messages:

{
  "method": "GET",
  "path": "/{account_id}/messages",
  "matrix": {
    "daterange": "2026-05-01T00:00:00Z,2026-05-20T00:00:00Z"
  },
  "query": {
    "addevents": true,
    "sortfield": "INSERTED",
    "sortorder": "ASC"
  },
  "range": "items=:10"
}

List flows through the convenience tool:

{
  "resource": "flows"
}

Submit a message, only with SENDPRO_READ_ONLY=false:

{
  "body": {
    "messageType": "EMAIL",
    "headerFromAddress": "[email protected]",
    "headerToAddress": "[email protected]",
    "subject": "Hello",
    "text": "Message body"
  }
}

Development

npm install
npm run check

Useful commands:

npm run dev
npm run build
npm run typecheck
npm test
npm run inspect

For repository structure, badges, release hygiene, and maintenance settings, see docs/repository-health.md.

Publishing

This package is published to npm as sendpro-flowmailer-mcp, and the repository includes MCP Registry metadata for registry submission.

For npm:

npm publish --access public

For the official MCP Registry, publish server.json after the npm package exists. The npm package includes:

{
  "mcpName": "io.github.mestika/sendpro-flowmailer-mcp"
}

Releases and Versions

This project uses semantic version tags such as v0.1.0, v0.1.1, and v1.0.0.

Use:

npm run version:patch  # bug fixes and small documentation-only release updates
npm run version:minor  # new backwards-compatible tools or features
npm run version:major  # breaking changes
git push origin main --follow-tags

Then create a GitHub Release from the new tag. The GitHub Release is the public changelog entry; the Git tag is the exact source snapshot. See docs/releasing.md for the full checklist.

Security

Never commit real SendPro credentials. Use MCP client environment variables, shell environment variables, or a local .env file.

See SECURITY.md for vulnerability reporting and operational notes.

License

MIT. See LICENSE.