# Banger API guide

Canonical URL: https://bangermail.com/api.md
Reference date: 2026-09-29
API origin: `https://api.bangermail.com`
Remote MCP endpoint: `https://api.bangermail.com/mcp`

Banger exposes company email operations through HTTP and remote MCP. Use the [product guide](https://bangermail.com/index.md) for capabilities and the [complete MCP reference](https://bangermail.com/mcp.md) for all 191 tool descriptions and exact typed inputs.

## Authentication and workspace selection

Remote MCP supports OAuth 2.1 authorization code with S256 PKCE. A compatible client discovers Banger's protected-resource and authorization-server metadata, opens the Banger authorization flow, and receives credentials after the user chooses and authorizes access. Passwords, email verification codes, and session cookies belong in the private authentication flow.

Scripts and supported non-interactive integrations can use workspace API keys. Store a key in an environment variable such as `BANGER_API_KEY`, outside source control. Send it with `Authorization: Bearer <key>`. The email gateway below uses a workspace API key.

An MCP credential binds the caller to a workspace and scopes. MCP tool arguments do not accept `workspace_id`; product-scoped operations can accept `product_id`. The tool catalog is filtered by granted scopes, and underlying operations enforce authorization again.

Representative scopes include `mail:read`, `mail:write`, `mail:send`, `contacts:read`, `contacts:write`, `campaigns:read`, `campaigns:write`, `campaigns:send`, `automation:read`, `automation:execute`, and connection-management scopes. Request the permissions your integration needs. Revocation and missing scope can invalidate previously working operations.

## Send an email over HTTP

The `POST /emails` gateway accepts a Resend-compatible email body. It requires `from`, `to`, and `subject`, plus HTML or plain text. The sender must be authorized and ready to send. Optional fields include cc, bcc, reply-to, headers, tags, and attachments according to the gateway contract.

This example sends an email when executed. Replace the illustrative addresses with an authorized sender and intended recipient.

```sh
curl https://api.bangermail.com/emails \
  -H "Authorization: Bearer $BANGER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-order-123-v1" \
  -d '{
    "from": "billing@your-verified-domain.com",
    "to": "customer@example.com",
    "subject": "Your receipt",
    "text": "Thank you. Your order has been received."
  }'
```

An accepted response contains an `id`. Acceptance is not delivery confirmation. Follow the send using delivery records and status tools. Keep the same idempotency key when retrying the same logical request; use a different key for a genuinely new send. Do not silently alter a payload while reusing its identity.

The mailbox-based MCP send interface has its own schema, including a mailbox ID and reply-to. Do not copy REST gateway fields into an MCP call without checking the tool definition.

## MCP transport

Banger uses stateless remote MCP over HTTP POST with JSON-RPC 2.0. Supported methods include `initialize`, `notifications/initialized`, `ping`, `tools/list`, and `tools/call`.

Send one message per POST with:

- `Authorization: Bearer <access-token-or-supported-api-key>`
- `Content-Type: application/json`
- `Accept: application/json, text/event-stream`
- The negotiated `MCP-Protocol-Version` after initialization.

Responses are JSON; notifications receive an accepted response. The server does not maintain an SSE stream: GET returns 405. Batching is unsupported and request bodies are limited to 256 KiB. The transport does not depend on a persistent `MCP-Session-Id`.

Let an MCP client handle initialization, OAuth, and protocol negotiation. Once initialized, tool discovery uses this JSON-RPC body:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

A read-only product-discovery call uses:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "banger_list_products",
    "arguments": {}
  }
}
```

Use public `banger_...` tool names, not a particular host application's connector namespace. Inspect the live schema before constructing write calls.

## Common integration workflows

### Product onboarding

Discover the existing workspace/product setup, select the intended product, and inspect the onboarding state. Configure a domain or starter mailbox, follow the private setup steps, verify readiness, and inspect an activation proof before claiming the domain can send.

Relevant tools: `banger_list_products`, `banger_onboarding_get_state`, `banger_onboarding_propose_plan`, `banger_create_native_sending_domain`, `banger_verify_native_sending_domain`, and `banger_get_domain_activation_proof`.

### Transactional email and Journeys

Use the email gateway for a direct application send. For a reusable Journey, register a stable key with its sender, delivery class, typed variables, and managed content; render sample data; obtain first-activation review; then activate and enroll or trigger it through its integration. Inspect executions and delivery state.

Relevant tools: `banger_register_api_journey`, `banger_render_journey`, `banger_preview_journey_approval`, `banger_set_journey_status`, `banger_enroll_journey_contacts`, and `banger_list_journey_executions`.

### Broadcast preparation and delivery

Create a draft, select a list or segment, preview the audience, render and review the email, and check readiness. Send or schedule only the intended revision. Inspect recipients and timeline records after execution.

Relevant tools: `banger_create_broadcast`, `banger_preview_broadcast_audience`, `banger_check_broadcast_readiness`, `banger_schedule_broadcast`, `banger_send_broadcast`, and `banger_list_broadcast_timeline`.

### Event integration

Create an incoming webhook for an approved product integration. Obtain its credentials through the private credential panel or the Banger web app; configure the source application; send a test event; inspect receipt evidence; then use the returned connection in a Journey trigger. Creating the endpoint alone does not activate the Journey.

Relevant tools: `banger_create_incoming_webhook`, `banger_list_webhooks`, `banger_test_webhook`, and `banger_set_webhook_status`.

## Operational rules

- Check the response's actual state. A draft is not sent, an accepted operation is not delivered, and an endpoint's existence is not evidence that an event arrived.
- Use idempotency keys where the operation requires them. Do not blindly retry non-idempotent creation operations, including webhook or API-key creation.
- Preserve revision and optimistic-concurrency fields where required. Reload and reconcile conflicting edits instead of overwriting another person's work.
- Preview and readiness operations are separate from send, publish, schedule, activate, and enroll operations.
- The first Journey activation requires human review. Other operations follow their applicable saved policies; the server's current result determines whether execution is allowed or awaiting review.
- Recipient suppression, expiry, limits, and domain readiness remain enforced even when an agent requests execution.
- Handle credentials through private setup flows. Inspect authentication and authorization failures before retrying a mutation.
- Use delivery status, logs, and sending-health tools to investigate failures.

## REST coverage and interface availability

The repository's HTTP contract includes workspace and mailbox management, messages and threads, drafts, contacts and segments, templates, Journeys, campaigns/Broadcasts, send records, connections, and delivery diagnostics. These interfaces share product state with the visual app and MCP.

This guide documents the email gateway and current MCP surface concretely. It is not a replacement for a versioned REST contract for every route. Use the supported SDK or integration contract supplied for your environment when building against additional HTTP routes. CLI and SDK package availability should be verified before installation; internal package names are not public installation instructions.

- [MCP client setup](https://bangermail.com/banger-mcp/)
- [MCP tool schemas](https://bangermail.com/mcp.md)
- [Bangerverse integration contract](https://github.com/bangermail/bangerverse/blob/main/docs/integration-contract.md)
- [Product reference](https://bangermail.com/index.md)