Developer docs

REST entry points for tracking, forms, API keys, and integrations

Everything you need to send events, embed forms, manage API keys, and wire up integrations — across Envoi's public ingestion APIs, scoped server APIs, and webhooks.

Build in Envoi Explore workflows

Public ingestion API

CORS-enabled endpoints for tracking snippets and hosted forms.

POST/api/public/page

Record a page view

Accepts siteId, visitorId, url, referrer, and title. Stores a durable page.viewed TrackingEvent and can trigger automations.

POST/api/public/track

Record a custom event

Accepts siteId, visitorId, event, properties, url, and referrer. Email properties can resolve or create a contact.

POST/api/public/identify

Identify a visitor

Accepts siteId, visitorId, email, and properties. Stitches prior anonymous events to the resolved contact.

GET/api/public/forms/{formId}/embed.js

Load a form embed

Serves the hosted form script. The script shares the _envoi_vid visitor id with onsite tracking before submit/view calls.

POST/api/public/forms/{formId}/submit

Submit a public form

Validates required fields, creates or updates the contact, records the submission, and writes form.submitted tracking activity.

Authenticated analytics surfaces

Dashboard/session APIs that read collected TrackingEvent data back into product workflows.

/api/analytics — campaign and web activity metrics, including TrackingEvent-derived visitors/top events/page views.
/api/contacts/{id}/activity — authenticated contact timeline reading TrackingEvent page/custom events.
/api/segments/preview — behavioral segment preview can resolve TrackingEvent predicates into contact filters.
/api/logs?type=webhooks|ai|usage|email|sms|api — authenticated org audit/debug feed for developer:manage roles, covering external events, idempotency deliveries, AI usage, API-key requests, and send status.

Scoped server API

POST/api/events

Emit a server-side event

Requires Authorization: Bearer <API key> or x-api-key with the events:write scope. Records a server TrackingEvent, links contactId or email, triggers flows, applies the key rate limit, and writes an API request log.

curl -X POST https://app.envoi.example/api/events   -H "Authorization: Bearer env_..."   -H "Content-Type: application/json"   -d '{"event":"purchase.completed","email":"buyer@example.com","properties":{"orderId":"ord_1"}}'

Copy-paste examples

Track an anonymous visitor

fetch('/api/public/track', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    siteId: 'site_...',
    visitorId: 'visitor_...',
    event: 'product.viewed',
    url: 'https://shop.example/products/hat',
    properties: { productId: 'hat_1' }
  })
})

Identify and stitch a visitor to a contact

fetch('/api/public/identify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    siteId: 'site_...',
    visitorId: 'visitor_...',
    email: 'buyer@example.com',
    properties: { firstName: 'Buyer' }
  })
})

Submit a hosted form with visitor context

fetch('/api/public/forms/form_123/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fields: { email: 'buyer@example.com' },
    metadata: { visitorId: 'visitor_...', source: 'landing-page' }
  })
})

Receive an integration webhook

curl -X POST https://app.envoi.example/api/webhooks/int_123   -H "x-envoi-signature: sha256=..."   -H "Content-Type: application/json"   -d '{"event":"order.created","email":"buyer@example.com"}'

Integrations

/api/integrations — list/create user-owned integrations from the authenticated dashboard session.

/api/integrations/{id} — read/update/delete one integration without exposing stored credentials.

/api/integrations/{id}/test — run the provider probe when one exists and persist status/sync errors.

/api/webhooks/{integrationId} — receive signed or secret-backed custom integration events.

/api/integrations/shopify/install and /callback — start and complete Shopify OAuth when Shopify env vars are configured.

Webhook security expectations

Provider webhooks should fail closed when signing secrets are missing. Custom integration webhooks should use each integration's webhook URL and rotated secret, then verify received events in the integration detail event log.