1---
2name: sendpulse-agent-api
3description: "Use when the task involves SendPulse integrations, MCP setup, REST API usage, auth selection between API key and OAuth, OpenAPI/documentation updates, or proposing improvements to SendPulse's API developer experience for agent-friendly workflows."
4---
5 
6# SendPulse Agent API
7 
8Use this skill to work with SendPulse as an API-first, agent-friendly platform.
9Favor flows that help AI agents and developers act through SendPulse with minimal friction.
10 
11## Official Source of Truth
12 
13Use these pages first instead of guessing:
14 
15- REST API docs and auth: `https://sendpulse.com/integrations/api`
16- MCP setup guide: `https://sendpulse.com/knowledge-base/account-settings/mcp-server`
17- MCP tools list: `https://sendpulse.com/knowledge-base/account-settings/mcp-tools`
18- MCP product page: `https://sendpulse.com/features/mcp`
19 
20If a public OpenAPI spec URL is not explicitly available, treat the REST API docs page as the current public source of truth.
21 
22## Start by Classifying the Request
23 
24Put the task into one of these buckets:
25 
261. MCP integration
272. Direct REST API integration
283. Authentication choice or migration
294. OpenAPI or developer docs update
305. Product/API UX improvement proposal
31 
32Do not mix all five at once.
33Solve the primary path first.
34 
35## Choose the Integration Surface First, Then Choose Auth
36 
37Do this in order:
38 
391. Decide whether the task is MCP or direct REST API.
402. For REST API tasks, choose API key vs OAuth.
413. For MCP tasks, follow the client-specific auth flow from the MCP docs.
42 
43Do not assume MCP auth works the same way as REST auth.
44 
45## Prefer the Right Surface
46 
47### Use MCP when
48 
49- the user wants AI assistants to operate SendPulse directly
50- the workflow is prompt-driven and tool-based
51- the goal is to connect OpenAI, Claude, Cursor, or another MCP client
52- the request is about account actions, campaign operations, CRM/chatbot tasks, or agent workflows
53 
54### Use direct REST API when
55 
56- the integration is backend-to-backend
57- the caller wants deterministic API contracts
58- the task is SDK, webhook, OpenAPI, or endpoint-level work
59- the integration should run without an MCP client in the middle
60 
61If both are viable, treat MCP as the fastest path for agent workflows and REST API as the canonical integration surface.
62 
63For connection and auth details, read `references/auth-and-connection.md`.
64 
65## MCP Auth Is Client-Specific
66 
67Do not describe MCP auth as only "API key vs OAuth."
68 
69Use the official MCP setup guide and follow the client flow:
70 
71- OpenAI: add the MCP server URL and use custom headers `X-SP-ID` and `X-SP-SECRET`
72- Cursor: add the MCP server URL in config, then complete the browser authorization flow when prompted
73 
74Official MCP server URL:
75`https://mcp.sendpulse.com/mcp`
76 
77## REST API Auth
78 
79Use the REST API docs for exact auth behavior:
80`https://sendpulse.com/integrations/api`
81 
82REST supports:
83 
84- API key: static long-lived credential, sent as `Authorization: Bearer <api_key>`
85- OAuth 2.0 client credentials: obtain token from `POST https://api.sendpulse.com/oauth/access_token`, then send it as `Authorization: Bearer <access_token>`
86 
87### Prefer API key when
88 
89- the integration is simple and long-lived
90- the user wants fewer moving parts
91- token refresh logic adds unnecessary complexity
92- the goal is fast setup for internal tools, prototypes, or agent connections
93 
94### Prefer OAuth when
95 
96- temporary credentials are required
97- the integration already expects token lifecycle management
98- security policy prefers short-lived access tokens
99- the task is specifically about OAuth client credentials or app-market authorization flows
100 
101Frame the trade-off clearly:
102 
103- API key = simpler setup, persistent secret, fast adoption
104- OAuth = more moving parts, short-lived tokens, cleaner temporary access model
105 
106## First Successful Request
107 
108For REST API work:
109 
1101. Authenticate.
1112. Send a safe read-only request to `GET https://api.sendpulse.com/user/info`.
1123. Only after that, continue to the requested endpoint.
113 
114For MCP work:
115 
1161. Connect the MCP server in the target client.
1172. Verify the available tools in the client or in the official tools list.
1183. Run one harmless read-only request first, such as account info or bot listing.
1194. Only then allow write actions.
120 
121## Real-Task Workflow
122 
123When handling a SendPulse request:
124 
1251. Classify the task: MCP, REST, auth, docs, or product/DX.
1262. Open the relevant official doc page.
1273. Pick the auth method explicitly.
1284. Verify with one safe read-only action.
1295. Execute the requested task.
1306. If the task is docs/DX-related, cite the exact official page being improved.
131 
132## Direct REST Scripts
133 
134Use these bundled scripts for direct REST work:
135 
136- `scripts/rest_api_key_smoke.sh` — smoke test with API key against `/user/info`
137- `scripts/rest_oauth_smoke.sh` — get OAuth token, then smoke test `/user/info`
138- `scripts/rest_request.sh` — generic REST request helper with Bearer auth
139- `scripts/mcp_handshake_test.py` — raw MCP auth/initialize/tools-list verification
140 
141Read the script first if you need to adapt arguments or environment variables.
142Default to dry-run before using real credentials.
143 
144Current validation status:
145 
146- `rest_api_key_smoke.sh` — syntax-checked, dry-run tested, and live-verified against `/user/info`
147- `rest_request.sh` — syntax-checked, dry-run tested, and live-verified against `/user/info`
148- `rest_oauth_smoke.sh` — syntax-checked and dry-run tested; live OAuth verification still requires `client_id` + `client_secret`
149- `mcp_handshake_test.py` — live-verified with SendPulse MCP auth, `initialize`, `notifications/initialized`, and `tools/list`
150- `mcp_call_tool.py` — live-verified for raw MCP `tools/call`; confirmed with safe read-only calls `chatbots_account_show` and `chatbots_bots_list`
151 
152## Important Ambiguity to Resolve Explicitly
153 
154The public docs currently show different credential patterns across surfaces:
155 
156- REST API key bearer auth
157- REST OAuth client credentials
158- MCP OpenAI custom headers: `X-SP-ID` / `X-SP-SECRET`
159- MCP Cursor browser authorization
160 
161Do not collapse these into one generic auth explanation.
162Name the exact flow for the target client or integration.
163 
164## Documentation and OpenAPI Work
165 
166When updating docs or drafting improvements:
167 
168- optimize for discoverability first
169- show the happy path before advanced variants
170- keep auth examples parallel: API key and OAuth side by side
171- include copy-paste request examples
172- name the right endpoint, headers, and token/key location clearly
173- separate MCP setup docs from raw REST API docs so users do not confuse them
174- treat OpenAPI as a product surface, not just a reference dump
175 
176A good SendPulse API doc should answer, in order:
177 
1781. What can I do?
1792. Which surface should I use: MCP or REST?
1803. How do I authenticate?
1814. What is the first successful request?
1825. What are the common failure modes?
183 
184For product framing and likely improvement directions, read `references/product-direction.md`.
185 
186## Product and DX Framing
187 
188When proposing improvements, bias toward agent usability and lower setup friction.
189Strong directions include:
190 
191- fewer steps from account to first successful API call
192- side-by-side examples for API key and OAuth
193- clearer MCP onboarding for OpenAI/Claude/Cursor
194- better OpenAPI coverage and examples
195- endpoint naming and parameter docs that work well for both humans and agents
196- predictable error handling and explicit rate-limit guidance
197 
198Treat inter-agent communication as a first-class product direction.
199If a design choice makes API usage easier for agents without hurting normal developers, prefer it.
200 
201## Deliverables
202 
203When answering, tailor the output to the task:
204 
205- setup task -> return exact connection/auth steps
206- integration task -> return endpoint flow, headers, and example requests
207- docs task -> return a proposed doc structure or rewritten section
208- product task -> return concrete DX improvements prioritized by impact and implementation effort
209 
210Keep the answer practical.
211Prefer one recommended path and one fallback.
212