API Reference

6 min read Last updated: June 23, 2026

REST API

ProperSend provides a REST API for programmatic integration with your existing tools, scripts, and workflows.

When to use the API: You need to automate lead imports, sync campaign data to an external CRM, build custom dashboards, or trigger actions based on ProperSend events.

Authentication

All API requests require authentication via a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer pro_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate API keys in Settings → API Keys with the specific scopes you need. See Settings for full account configuration.

Scopes

Each API key is scoped to specific resources for security:

| Scope | Access | |-------|--------| | crm:read | Read leads, lists, and notes | | crm:write | Create and update leads | | campaigns:read | View campaigns and their status | | campaigns:write | Create, update, and launch campaigns | | mailboxes:read | View mailbox status and reputation | | analytics:read | Access campaign statistics and reports |

Best Practice: Create separate API keys for different use cases — one for your reporting dashboard (read-only scopes), another for your lead import script (crm:write). This limits risk if a key is compromised. Generate and revoke keys from Integrations.

Example API call (cURL):

curl https://api.propersend.pl/v1/crm/leads \
  -H "Authorization: Bearer pro_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Rate Limiting

To ensure fair usage, API requests are rate-limited:

| Limit | Window | |-------|--------| | 60 requests | 1 minute | | 1000 requests | 1 hour |

If you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your integration to handle this gracefully.

Endpoints

Full endpoint documentation with request/response schemas is available in the Swagger UI. The main endpoint groups are:

  • CRM – list, search, create, update, and delete leads. See CRM for features.
  • Campaigns – manage campaigns, start/stop, view statistics
  • Mailboxes – check mailbox status and reputation. See Mailboxes.
  • Analytics – aggregated campaign performance data
  • Webhooks – configure and test webhook endpoints. See Integrations.

MCP Server

ProperSend provides a Model Context Protocol (MCP) Server for AI agent integration. This allows AI coding assistants (Cursor, Claude, ChatGPT) to interact with your ProperSend data directly.

Available MCP tools:

| Tool | Description | |------|-------------| | crm_search | Search leads in CRM by criteria | | crm_get | Get detailed lead information | | campaign_list | List all campaigns with status | | campaign_get | Get campaign details and statistics | | mailbox_list | List connected mailboxes and status |

Configure the MCP Server in your AI assistant settings using the endpoint and API key from your Integrations page. See Integrations → MCP Server for setup instructions.