Developers

Developer documentation

Guides for tracking events, sending transactional email, building automations, managing contacts, campaigns, and forms, plus connecting AI agents with OnePush MCP.

Overview

OnePush is built around contacts, events, and actions. When you track an event, OnePush creates or updates a contact and can trigger automated email sequences (actions). For one-off sends, use the transactional email endpoint. Campaigns, templates, and forms extend the same contact model. AI agents can use the same project through a hosted MCP server.

Quickstart

Create an account, open Settings → API Keys in the dashboard, and copy your project keys. Use your secret key (sk_) to send email and your public or secret key (pk_ or sk_) to track events. Verify your sending domain before your first production send. To connect Cursor or Claude, approve an MCP key instead of sharing your secret key.

Authentication

Authenticate API requests with a Bearer token in the Authorization header. Public keys (pk_) are for event tracking. Secret keys (sk_) are required for sending email, managing forms, and sending campaigns. Enterprise keys (ek_) are used for the enterprise provisioning API. For AI agents, use a dedicated MCP key (mcp_) from the connect page or Settings → MCP, you can revoke it without rotating sk_ or pk_.

Authorization: Bearer sk_xxxxxxxxxxxx

MCP for AI agents

OnePush hosts a remote Model Context Protocol (MCP) endpoint for Cursor, Claude, and other assistants. Approve a dedicated mcp_ key in the browser, paste it into your client, then manage contacts, email, domains, forms, billing, and social from chat. Full client setup, tool catalog, and example prompts live on the MCP docs pages.

MCP URL:  https://api.onepush.app/mcp
Approve:  https://ctl.onepush.app/mcp/connect

Cursor / Claude MCP config

Add OnePush as a remote MCP server with your mcp_ key. Prefer keys from the connect page. They are revocable without rotating sk_/pk_. See the MCP Server page for Claude Code, Gemini CLI, VS Code, and ChatGPT.

{
  "mcpServers": {
    "onepush": {
      "url": "https://api.onepush.app/mcp",
      "headers": {
        "Authorization": "Bearer mcp_xxxxxxxxxxxx"
      }
    }
  }
}

Track events and automations

Call POST /v1/track when a user performs an action in your app, such as sign-up, purchase, or trial started. OnePush creates the contact if needed and runs any actions (automations) linked to that event. Attach optional metadata to personalize downstream emails.

curl -X POST https://api.onepush.app/v1/track \
  -H "Authorization: Bearer pk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "signup",
    "email": "user@example.com",
    "data": {
      "first_name": { "value": "Alex", "persistent": true }
    }
  }'

Send transactional email

Send a one-off email with POST /v1/send. Requires a verified domain and a secret key. Pass to (single address or array), subject, and body (plain text or HTML). Optional fields include from, name, reply, headers, and attachments.

curl -X POST https://api.onepush.app/v1/send \
  -H "Authorization: Bearer sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to OnePush",
    "body": "<p>Thanks for signing up.</p>"
  }'

Forms

Build forms in the dashboard, embed them with a single script tag (GET /forms/:id/embed.js), or accept submissions via POST /forms/:id/submit. Manage forms programmatically with the /v1/forms endpoints using your secret key.

Social publishing

Connect social profiles in the dashboard, then create, schedule, and publish posts from the Social Delivery workspace. Social endpoints are available through the authenticated project API, connect accounts at Settings and publish from the dashboard or your integration.

Going to production

Verify your sending domain in the dashboard, configure SPF/DKIM/DMARC, test with a small volume, and monitor delivery in Email logs. Use GET /health to check API availability. For compliance questions, review our GDPR and DPA pages.