1# SendPulse auth and connection notes
2 
3## Official pages
4 
5Use these pages as the default public source of truth:
6 
7- REST API docs: `https://sendpulse.com/integrations/api`
8- MCP setup guide: `https://sendpulse.com/knowledge-base/account-settings/mcp-server`
9- MCP tools list: `https://sendpulse.com/knowledge-base/account-settings/mcp-tools`
10- MCP product page: `https://sendpulse.com/features/mcp`
11 
12## REST API basics
13 
14- Root URL: `https://api.sendpulse.com`
15- Transport: HTTPS
16- Response format: JSON
17- Authorization header for API requests:
18  - `Authorization: Bearer <your_token_or_key>`
19 
20## REST auth option 1 — API key
21 
22Use when setup speed and operational simplicity matter most.
23 
24Key properties:
25 
26- static, long-lived credential
27- valid until manually revoked
28- generated in SendPulse account settings under API
29- up to 5 independent keys
30- can be restricted by IP address
31 
32Good fit:
33 
34- internal integrations
35- backend services
36- prototypes
37- agent workflows where token refresh is unnecessary complexity
38 
39## REST auth option 2 — OAuth 2.0 client credentials
40 
41Use when short-lived access is preferred.
42 
43Token request:
44 
45- `POST https://api.sendpulse.com/oauth/access_token`
46- required parameters:
47  - `grant_type=client_credentials`
48  - `client_id`
49  - `client_secret`
50 
51Behavior:
52 
53- returns a Bearer token
54- token lifetime is about 1 hour
55- request a new token only after expiry
56 
57Good fit:
58 
59- environments that already handle token refresh
60- integrations with stricter secret-lifetime requirements
61- work specifically centered on OAuth flows
62 
63## MCP basics
64 
65Official MCP server URL:
66 
67- `https://mcp.sendpulse.com/mcp`
68 
69Conceptual flow:
70 
711. user asks the AI assistant for an action
722. client sends the request to the MCP server
733. MCP server calls SendPulse API
744. result returns to the client chat
75 
76## MCP auth is not the same as REST auth
77 
78Do not collapse MCP auth into the API key vs OAuth explanation.
79Use client-specific setup.
80 
81### OpenAI-style MCP setup
82 
83According to SendPulse docs, the connection flow requires:
84 
85- adding a new MCP server in the client
86- pasting the SendPulse MCP URL
87- using custom headers for auth:
88  - `X-SP-ID`
89  - `X-SP-SECRET`
90 
91The docs say to copy ID and Secret values from Account settings > API.
92 
93### Cursor setup notes
94 
95SendPulse docs show a minimal MCP config that points Cursor to:
96 
97```json
98{
99  "mcpServers": {
100    "sendpulse_mcp_service": {
101      "url": "https://mcp.sendpulse.com/mcp"
102    }
103  }
104}
105```
106 
107Then complete authorization in the browser flow if prompted.
108 
109## First-success validation
110 
111### REST
112 
113Use `GET https://api.sendpulse.com/user/info` as the default smoke test.
114 
115Bundled scripts:
116 
117- `scripts/rest_api_key_smoke.sh` — live-verified with API key on `/user/info`
118- `scripts/rest_oauth_smoke.sh` — dry-run verified, waiting for live OAuth creds
119- `scripts/rest_request.sh` — live-verified with Bearer auth on `/user/info`
120 
121### MCP
122 
123Before promising a tool exists:
124 
1251. check the client's visible tools list
1262. cross-check the official tools page: `https://sendpulse.com/knowledge-base/account-settings/mcp-tools`
1273. run one harmless read-only task first
128 
129## Useful framing sentence
130 
131Use this wording when helpful:
132 
133`MCP is the fastest way to let an AI assistant operate your SendPulse account, while the REST API remains the canonical surface for direct backend integrations.`
134