# Nitrosend API

> Multi-channel marketing automation API. Send email campaigns, build automation flows, manage contacts and segments, track events, and configure your brand.

## MCP Server (AI Agents)

Nitrosend exposes an MCP (Model Context Protocol) server for AI agents at:

    https://api.nitrosend.com/mcp

### Connecting by client

Auth is OAuth 2.1, auto-discovered by the client. No API key needed — the agent opens a browser for sign-in.

**Claude Code:**
```bash
claude mcp add --transport http nitrosend https://api.nitrosend.com/mcp
```

**Claude Desktop / Claude.ai / Cowork:**
Settings → Connectors → Add Custom Connector → `https://api.nitrosend.com/mcp`

**ChatGPT:**
Settings → Apps → Advanced settings → enable Developer mode, then Settings → Apps → Create app for a remote MCP server → `https://api.nitrosend.com/mcp`

**Cursor**:
```json
{"mcpServers": {"nitrosend": {"url": "https://api.nitrosend.com/mcp"}}}
```

**VS Code (Copilot)** — add to `.vscode/mcp.json`:
```json
{"servers": {"nitrosend": {"type": "http", "url": "https://api.nitrosend.com/mcp"}}}
```

**Windsurf** — add to `~/.codeium/windsurf/mcp_config.json`:
```json
{"mcpServers": {"nitrosend": {"serverUrl": "https://api.nitrosend.com/mcp"}}}
```

**Codex CLI:**
```bash
codex mcp add nitrosend --url https://api.nitrosend.com/mcp
codex mcp login nitrosend
```

**Gemini CLI** — add to `~/.gemini/settings.json`:
```json
{"mcpServers": {"nitrosend": {"httpUrl": "https://api.nitrosend.com/mcp"}}}
```

**Zed**:
```json
{"context_servers": {"nitrosend": {"url": "https://api.nitrosend.com/mcp"}}}
```

**Any other HTTP-capable MCP client:**
Point at `https://api.nitrosend.com/mcp` using HTTP/Streamable HTTP transport.

**stdio-only clients** (API key required):
```json
{"command": "npx", "args": ["-y", "@nitrosend/mcp"], "env": {"NITROSEND_API_KEY": "nskey_live_..."}}
```

Example workflows: https://docs.nitrosend.com/guides/mcp-examples

### OAuth 2.1 Authentication

Auth is auto-discovered per RFC 9728 + RFC 8414. The flow:

1. Client POSTs to `/mcp` → receives `401` with `WWW-Authenticate` header containing the resource metadata URL
2. Client fetches `/.well-known/oauth-protected-resource/mcp` → gets authorization server URL
3. Client fetches `/.well-known/oauth-authorization-server` → gets authorize/token/register endpoints
4. Client registers dynamically via `POST /oauth/register` (RFC 7591)
5. Client runs standard OAuth 2.1 authorization code + PKCE flow
6. Client uses Bearer token for all subsequent MCP requests

### Alternative: API Key Auth

For scripts and non-interactive use, pass an API key as a Bearer token:

    Authorization: Bearer nskey_live_...

Get an API key from Settings > API Keys in the Nitrosend dashboard (https://app.nitrosend.com/my/settings/api-keys).

### MCP Tools

Once connected, agents have access to tools for managing campaigns, flows, contacts, segments, templates, domains, brands, and more. Read the `nitro://guide` resource after connecting for the full tool list and workflow.

## REST API

- **OpenAPI spec:** https://api.nitrosend.com/openapi.yaml
- **Base URL:** https://api.nitrosend.com

### Authentication

All REST endpoints require a Bearer token:

1. **API Key** — `Authorization: Bearer nskey_live_...`
2. **JWT** — `Authorization: Bearer <jwt>` (from `POST /v1/login`)

### Resources

- **Contacts** — `/v1/my/contacts` — create, update, search, enrich contacts
- **Lists** — `/v1/my/lists` — named contact collections
- **Segments** — `/v1/my/segments` — dynamic audience filters
- **Campaigns** — `/v1/my/campaigns` — email/SMS broadcasts with scheduling
- **Flows** — `/v1/my/flows` — event-triggered automation sequences
- **Templates** — `/v1/my/templates` — reusable email designs
- **Events** — `/v1/my/events` — custom contact event tracking
- **Messages** — `/v1/my/messages` — transactional email/SMS sends
- **Domains** — `/v1/my/domains` — sending domain verification
- **Brands** — `/v1/my/brands` — brand identity, colors, fonts, tone
- **Account** — `/v1/my/account` — account settings, onboarding

### Pagination

Paginated endpoints accept `page` and `limit` query params. Max 100, default 30.

Response headers: `X-Total-Count`, `X-Total-Pages`, `X-Page-Number`.

### Errors

```json
{
  "code": 422,
  "message": "Description of error",
  "error": true,
  "validation_errors": { "field": ["error message"] }
}
```

## SDK

```bash
npm install @nitrosend/sdk
```

```ts
import { Nitrosend } from '@nitrosend/sdk';
const ns = new Nitrosend('nskey_live_...');

const contact = await ns.contacts.create({
  email: 'alice@example.com',
  firstName: 'Alice',
});
```

- Node.js SDK: https://www.npmjs.com/package/@nitrosend/sdk
- MCP bridge (npm): https://www.npmjs.com/package/@nitrosend/mcp