SendPulse Agent API

Use this skill to work with SendPulse as an API-first, agent-friendly platform. Favor flows that help AI agents and developers act through SendPulse with minimal friction.

Official Source of Truth

Use these pages first instead of guessing:

• REST API docs and auth: https://sendpulse.com/integrations/api
• MCP setup guide: https://sendpulse.com/knowledge-base/account-settings/mcp-server
• MCP tools list: https://sendpulse.com/knowledge-base/account-settings/mcp-tools
• MCP product page: https://sendpulse.com/features/mcp

If a public OpenAPI spec URL is not explicitly available, treat the REST API docs page as the current public source of truth.

Start by Classifying the Request

Put the task into one of these buckets:

1. MCP integration
2. Direct REST API integration
3. Authentication choice or migration
4. OpenAPI or developer docs update
5. Product/API UX improvement proposal

Do not mix all five at once. Solve the primary path first.

Choose the Integration Surface First, Then Choose Auth

Do this in order:

1. Decide whether the task is MCP or direct REST API.
2. For REST API tasks, choose API key vs OAuth.
3. For MCP tasks, follow the client-specific auth flow from the MCP docs.

Do not assume MCP auth works the same way as REST auth.

Prefer the Right Surface

Use MCP when

• the user wants AI assistants to operate SendPulse directly
• the workflow is prompt-driven and tool-based
• the goal is to connect OpenAI, Claude, Cursor, or another MCP client
• the request is about account actions, campaign operations, CRM/chatbot tasks, or agent workflows

Use direct REST API when

• the integration is backend-to-backend
• the caller wants deterministic API contracts
• the task is SDK, webhook, OpenAPI, or endpoint-level work
• the integration should run without an MCP client in the middle

If both are viable, treat MCP as the fastest path for agent workflows and REST API as the canonical integration surface.

For connection and auth details, read references/auth-and-connection.md.

MCP Auth Is Client-Specific

Do not describe MCP auth as only "API key vs OAuth."

Use the official MCP setup guide and follow the client flow:

• OpenAI: add the MCP server URL and use custom headers X-SP-ID and X-SP-SECRET
• Cursor: add the MCP server URL in config, then complete the browser authorization flow when prompted

Official MCP server URL: https://mcp.sendpulse.com/mcp

REST API Auth

Use the REST API docs for exact auth behavior: https://sendpulse.com/integrations/api

REST supports:

• API key: static long-lived credential, sent as Authorization: Bearer <api_key>
• OAuth 2.0 client credentials: obtain token from POST https://api.sendpulse.com/oauth/access_token, then send it as Authorization: Bearer <access_token>

Prefer API key when

• the integration is simple and long-lived
• the user wants fewer moving parts
• token refresh logic adds unnecessary complexity
• the goal is fast setup for internal tools, prototypes, or agent connections

Prefer OAuth when

• temporary credentials are required
• the integration already expects token lifecycle management
• security policy prefers short-lived access tokens
• the task is specifically about OAuth client credentials or app-market authorization flows

Frame the trade-off clearly:

• API key = simpler setup, persistent secret, fast adoption
• OAuth = more moving parts, short-lived tokens, cleaner temporary access model

First Successful Request

For REST API work:

1. Authenticate.
2. Send a safe read-only request to GET https://api.sendpulse.com/user/info.
3. Only after that, continue to the requested endpoint.

For MCP work:

1. Connect the MCP server in the target client.
2. Verify the available tools in the client or in the official tools list.
3. Run one harmless read-only request first, such as account info or bot listing.
4. Only then allow write actions.

Real-Task Workflow

When handling a SendPulse request:

1. Classify the task: MCP, REST, auth, docs, or product/DX.
2. Open the relevant official doc page.
3. Pick the auth method explicitly.
4. Verify with one safe read-only action.
5. Execute the requested task.
6. If the task is docs/DX-related, cite the exact official page being improved.

Direct REST Scripts

Use these bundled scripts for direct REST work:

• scripts/rest_api_key_smoke.sh — smoke test with API key against /user/info
• scripts/rest_oauth_smoke.sh — get OAuth token, then smoke test /user/info
• scripts/rest_request.sh — generic REST request helper with Bearer auth
• scripts/mcp_handshake_test.py — raw MCP auth/initialize/tools-list verification

Read the script first if you need to adapt arguments or environment variables. Default to dry-run before using real credentials.

Current validation status:

• rest_api_key_smoke.sh — syntax-checked, dry-run tested, and live-verified against /user/info
• rest_request.sh — syntax-checked, dry-run tested, and live-verified against /user/info
• rest_oauth_smoke.sh — syntax-checked and dry-run tested; live OAuth verification still requires client_id + client_secret
• mcp_handshake_test.py — live-verified with SendPulse MCP auth, initialize, notifications/initialized, and tools/list
• mcp_call_tool.py — live-verified for raw MCP tools/call; confirmed with safe read-only calls chatbots_account_show and chatbots_bots_list

Important Ambiguity to Resolve Explicitly

The public docs currently show different credential patterns across surfaces:

• REST API key bearer auth
• REST OAuth client credentials
• MCP OpenAI custom headers: X-SP-ID / X-SP-SECRET
• MCP Cursor browser authorization

Do not collapse these into one generic auth explanation. Name the exact flow for the target client or integration.

Documentation and OpenAPI Work

When updating docs or drafting improvements:

• optimize for discoverability first
• show the happy path before advanced variants
• keep auth examples parallel: API key and OAuth side by side
• include copy-paste request examples
• name the right endpoint, headers, and token/key location clearly
• separate MCP setup docs from raw REST API docs so users do not confuse them
• treat OpenAPI as a product surface, not just a reference dump

A good SendPulse API doc should answer, in order:

1. What can I do?
2. Which surface should I use: MCP or REST?
3. How do I authenticate?
4. What is the first successful request?
5. What are the common failure modes?

For product framing and likely improvement directions, read references/product-direction.md.

Product and DX Framing

When proposing improvements, bias toward agent usability and lower setup friction. Strong directions include:

• fewer steps from account to first successful API call
• side-by-side examples for API key and OAuth
• clearer MCP onboarding for OpenAI/Claude/Cursor
• better OpenAPI coverage and examples
• endpoint naming and parameter docs that work well for both humans and agents
• predictable error handling and explicit rate-limit guidance

Treat inter-agent communication as a first-class product direction. If a design choice makes API usage easier for agents without hurting normal developers, prefer it.

Deliverables

When answering, tailor the output to the task:

• setup task -> return exact connection/auth steps
• integration task -> return endpoint flow, headers, and example requests
• docs task -> return a proposed doc structure or rewritten section
• product task -> return concrete DX improvements prioritized by impact and implementation effort

Keep the answer practical. Prefer one recommended path and one fallback.