REST API overview
Complete REST API reference for managing email campaigns, lists, subscribers, segments, and the suppression list.
The MailingPlatform API gives you programmatic access to the same building blocks you use in the app. Every resource you manage in your dashboard - subscribers, lists, campaigns, templates, segments and the suppression list - has a matching set of REST endpoints, so anything you can click, you can automate.
The API is organized around resources. Each resource has its own page in this reference with a short explanation of how it works in the platform, the most common use cases, and every endpoint with parameters, example requests in curl and JavaScript, and example responses. All requests and responses use JSON.
Typical integrations
- Sync signups from your own website or backend into a list, with double opt-in handled for you.
- Migrate an existing audience with the bulk endpoint, preserving names, tags and custom fields.
- Create and send campaigns from your own tooling, for example a nightly digest built from your database.
- Keep your suppression list in sync with an external CRM so unsubscribes are respected everywhere.
- Feed website and store events into the platform to power segments and trigger automations.
Base URL
https://api.mailingplatform.netAuthentication
All API requests require authentication using a Bearer token. The recommended way is a dedicated API key, created on the API keys page in your dashboard:
Authorization: Bearer mp_live_...API keys are shown once at creation and can be revoked at any time. Each key is limited to the scopes you select:
subscribers:read/subscribers:write- Subscriber and bulk subscriber APIscampaigns:read/campaigns:write- Campaigns APIlists:read/lists:write- Email lists APIsegments:read/segments:write- Segments APIblacklist:read/blacklist:write- Blacklist APItemplates:read/templates:write- Templates APIall- Full access to every endpoint
Read scopes cover GET requests; write scopes are required for POST, PUT, and DELETE. A Supabase user JWT is also accepted as the Bearer token.
Keep your API key secret
Rate limits
Rate limits are applied per account and per endpoint group, so heavy use of one resource does not block the others. When you exceed a limit the API responds with 429 RATE_LIMIT_ERROR; wait and retry with exponential backoff.
Pagination
List endpoints return paginated results and accept a limit parameter (default 25 or 50 depending on the resource, max 100). Subscribers and segments use page numbers; campaigns and lists use an offset. Each response includes a pagination object telling you the total count and whether more results are available, so you can loop until you have everything.
Quickstart
Create a subscriber on a list. If your account has double opt-in enabled (Settings, GDPR), new subscribers start as pending and automatically receive a confirmation email.
curl -X POST "https://api.mailingplatform.net/subscriber-api/{listId}" \
-H "Authorization: Bearer mp_live_..." \
-H "Content-Type: application/json" \
-d '{
"email": "john@example.com",
"first_name": "John",
"last_name": "Doe",
"tags": ["customer", "newsletter"],
"custom_fields": {
"company": "Acme Corp",
"phone": "+1234567890"
},
"skip_confirmation": false
}'Response format
All API responses follow a consistent structure.
{
"success": true,
"data": { /* response data */ },
"message": "Operation completed successfully"
}Resources
What about automations?
Automation workflows are built and managed in the app; there is no dedicated automations endpoint yet. You can still start automations through the API: events sent to the website tracking endpoint fire matching triggers (custom event, website visit, product viewed), and store events arriving on the e-commerce webhook fire the store triggers. Event properties become merge tags in the automation's emails.
Need help?
If you have questions about the API or need assistance, please contact our support team through the support page.