Developers

Viperatron API Reference

One REST API for every product surface — send, import, automate, and analyze. JSON in, JSON out. Auth with a single header. OpenAPI 3 spec always live.

Download OpenAPI JSONJump to reference

Base URL

api.viperatron.com

Version

v1

Auth

Bearer API key

Format

JSON

QUICKSTART

Send your first email in 60 seconds

Generate an API key in Dashboard → Settings → API Keys, then make a single POST request.

curl -X POST https://api.viperatron.com/api/v1/delivery/send \
  -H "Authorization: Bearer et_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Welcome to Acme",
    "html": "<h1>Hi {{firstName}}</h1><p>Thanks for signing up.</p>",
    "from": "hello@acme.com"
  }'

Response: { "messageId": "msg_1a2b3c", "status": "queued" }

AUTH

Authentication

Every request authenticates with an API key you generate in the dashboard. Keys are scoped to one organization and hashed at rest.

Bearer token (recommended)

Authorization: Bearer et_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternate: X-API-Key header

X-API-Key: et_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Keep keys out of client-side code. API keys grant full access to your organization’s data. Store them as environment variables on your server and rotate them if ever exposed.

Rate limits

Each API key has a per-minute and per-day request budget. Defaults are 60 requests/min and 10,000 requests/day. Contact us for higher limits on Pro and Enterprise.

Every response carries rate-limit headers so you can back off gracefully. When a quota is exhausted the API returns 429 Too Many Requests with a Retry-After header.

# Success response headers
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 48
X-RateLimit-Reset-Minute: 32
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9187
# 429 response
Retry-After: 32

Common tasks

A handful of examples showing the three most common API surfaces. The full list lives in the reference below.

Send a transactional email

curl -X POST https://api.viperatron.com/api/v1/delivery/send \
  -H "Authorization: Bearer et_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Welcome to Acme",
    "html": "<h1>Hi {{firstName}}</h1><p>Thanks for signing up.</p>",
    "from": "hello@acme.com"
  }'

Create or update a contact

curl -X POST https://api.viperatron.com/api/v1/contacts \
  -H "Authorization: Bearer et_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "tags": ["newsletter", "early-access"],
    "customFields": { "plan": "pro" }
  }'

Ingest a pipeline event

curl -X POST https://api.viperatron.com/api/v1/pipelines/events \
  -H "Authorization: Bearer et_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "eventType": "order.placed",
    "value": 129.00,
    "currency": "USD",
    "properties": { "orderId": "ord_1a2b3c", "sku": "ACME-TEE-L" }
  }'

Core resources

Every resource follows REST conventions — GET, POST, PATCH, DELETE. List endpoints paginate with ?limit= and ?cursor=.

Delivery

POST /delivery/send

Send a transactional email through a verified sender.

Contacts

POST /contacts

Create or upsert a contact with tags and custom fields.

Campaigns

POST /campaigns/:id/send

Launch a broadcast campaign to a segment or list.

Pipelines

POST /pipelines/events

Stream site, purchase, or funnel events into a pipeline.

Automations

POST /automations/:id/enroll

Enroll a contact into a multi-step automation.

Analytics

GET /analytics/campaigns/:id

Query opens, clicks, bounces, and conversion rates.

LIVE REFERENCE

Interactive API reference

Browse every endpoint, try requests with your own API key, and see generated examples in cURL, Node, Python, PHP, Go, Ruby, and more.

Open Swagger UI
Loading interactive reference…

Build something great with Viperatron

Spin up a free account, create an API key, and ship your first integration today.

Create free accountRead the knowledge base