Developers

REST API reference

Base URL: https://api.onepush.app. Authenticate with Bearer tokens. JSON request and response bodies unless noted. MCP is available at https://api.onepush.app/mcp.

Authentication

Pass your API key in the Authorization header as Bearer <key>. Public keys (pk_) work for event tracking. Secret keys (sk_) are required for sending email, campaigns, and form management. Enterprise keys (ek_) are for the enterprise provisioning API. MCP uses dedicated mcp_ keys (preferred) or sk_. Create REST keys under Settings → API Keys; create MCP keys at /mcp/connect or Settings → MCP.

Authorization: Bearer sk_xxxxxxxxxxxx

MCP: POST /mcp

Remote Model Context Protocol (Streamable HTTP) for Cursor, Claude, and other MCP clients. Same host as the REST API. Anonymous calls expose help and start_onepush_connect only. Authenticated mcp_ or sk_ calls unlock project tools (contacts, events, automations, templates, campaigns, forms, domain DNS, billing reads, social). Approve keys in the dashboard; revoke anytime without rotating sk_/pk_.

# Endpoint
POST https://api.onepush.app/mcp
Authorization: Bearer mcp_xxxxxxxxxxxx

# Browser approve (preferred)
https://ctl.onepush.app/mcp/connect

# Stable redirect from API
GET  https://api.onepush.app/mcp/connect  →  302 https://ctl.onepush.app/mcp/connect

POST /v1/track

Track a user event. Creates or updates the contact and triggers any actions (automations) linked to the event. Accepts pk_ or sk_ keys. Reserved event names: subscribe and unsubscribe.

{
  "event": "signup",
  "email": "user@example.com",
  "subscribed": true,
  "data": {
    "plan": { "value": "pro", "persistent": true }
  }
}

POST /v1/send

Send a transactional email. Requires sk_ key and a verified sending domain. The to field accepts a string or array of addresses.

{
  "to": ["user@example.com"],
  "subject": "Order confirmed",
  "body": "<h1>Thanks for your order</h1>",
  "from": "noreply@yourdomain.com",
  "name": "Your App",
  "reply": "support@yourdomain.com"
}

Contacts: /v1/contacts

List, create, update, and delete contacts. Block, unblock, subscribe, unsubscribe, and manage tags. Requires sk_ key.

GET    /v1/contacts
GET    /v1/contacts/:id
GET    /v1/contacts/count
POST   /v1/contacts
PUT    /v1/contacts
DELETE /v1/contacts
POST   /v1/contacts/block
POST   /v1/contacts/unblock
POST   /v1/contacts/subscribe
POST   /v1/contacts/unsubscribe
PUT    /v1/contacts/tags

Actions (automations): /v1/actions

Create and manage automated email sequences triggered by events. Configure delays, templates, and conditions in the dashboard or via API.

GET    /v1/actions/:id
GET    /v1/actions/:id/related
POST   /v1/actions
PUT    /v1/actions
DELETE /v1/actions
POST   /v1/actions/clear-queue

Templates: /v1/templates

Create, duplicate, update, and delete reusable email templates used by actions and campaigns.

GET    /v1/templates/:id
POST   /v1/templates
POST   /v1/templates/duplicate
PUT    /v1/templates
DELETE /v1/templates

Campaigns: /v1/campaigns

Manage one-off email campaigns and send them to segmented contacts. Use POST /v1/campaigns/send to trigger delivery.

GET    /v1/campaigns/:id
POST   /v1/campaigns
POST   /v1/campaigns/send
POST   /v1/campaigns/duplicate
PUT    /v1/campaigns
DELETE /v1/campaigns

Forms: /v1/forms and public embed

Manage forms with the secret key. Embed on any site with the public script endpoint, or accept submissions directly.

GET    /v1/forms
GET    /v1/forms/:id
GET    /v1/forms/:id/submissions
GET    /v1/forms/:id/submissions/export.csv
POST   /v1/forms
PUT    /v1/forms
DELETE /v1/forms

# Public (no API key)
GET    /forms/:id/embed.js
POST   /forms/:id/submit

Tags: /v1/tags

List, create, and delete contact tags for segmentation.

GET    /v1/tags
POST   /v1/tags
DELETE /v1/tags

GET /health

Health check endpoint. Returns { "success": true } when the API is available.

curl https://api.onepush.app/health

System status page →

Delivery events

Email delivery, bounce, open, click, and complaint events are processed through AWS SES notifications. Configure your application to consume delivery data via the dashboard email logs and analytics. Incoming integration webhooks (Stripe, Shopify) are available for billing and commerce workflows.