Documentation

Everything you need to integrate Emivoy into your application.

Getting Started

Go from zero to your first notification in five steps.

1. Create an account

2. Configure your email provider

Go to Settings and add your SendGrid API key. Emivoy sends emails through your account — your domain, your deliverability, your reputation.

3. Create entities and contacts

# Create an entity
POST /api/v1/entities
{
  "external_id": "acct_123",
  "entity_type": "account",
  "name": "Acme Corp"
}

# Attach a contact
POST /api/v1/contacts
{
  "entity_id": "acct_123",
  "role": "billing_contact",
  "email": "billing@acme.com",
  "name": "Jane Smith"
}

4. Define a policy and template

Create an email template, then a policy that maps an event type to that template. Use the Console UI or the API.

# Create a template
POST /api/v1/templates
{
  "name": "Invoice Overdue",
  "subject": "Invoice #{{invoice_id}} is overdue",
  "text_body": "Hi {{contact_name}}, invoice #{{invoice_id}} for ${{amount}} is {{days_overdue}} days overdue.",
  "html_body": "<p>Hi {{contact_name}},...</p>"
}

# Create a policy
POST /api/v1/policies
{
  "name": "Invoice Overdue Notifications",
  "event_type": "invoice.overdue",
  "steps": [
    {"type": "send_email", "template_id": "tpl_..."},
    {"type": "wait", "duration": "3d"},
    {"type": "send_email", "template_id": "tpl_reminder_..."}
  ]
}

5. Send your first event

POST an event and Emivoy matches it to the policy, resolves contacts, renders templates, and delivers via your SendGrid account.

POST /api/v1/events
{
  "event_type": "invoice.overdue",
  "entity_id": "acct_123",
  "data": {
    "invoice_id": "INV-1042",
    "amount": 1200,
    "days_overdue": 7
  }
}

API Reference

All endpoints require authentication via API key or Clerk JWT.

POST /api/v1/events

Create an event. Triggers matching policies.

GET /api/v1/events

List events with pagination and filters.

POST /api/v1/entities

Create an entity.

GET /api/v1/entities

List entities with pagination and search.

POST /api/v1/contacts

Create a contact and attach to an entity with a role.

GET /api/v1/contacts

List contacts with pagination and search.

POST /api/v1/policies

Create a notification policy with steps.

GET /api/v1/policies

List policies.

POST /api/v1/templates

Create an email template.

GET /api/v1/templates

List templates.

POST /api/v1/api-keys

Create an API key. The key value is only returned once.

DELETE /api/v1/api-keys/:id

Revoke an API key.

Python Client

A Python client is available for programmatic access.

from emivoy import Client

client = Client(base_url="https://api.emivoy.com", api_key="em_live_...")

# Create an entity
entity = client.create_entity(
    external_id="acct_123",
    entity_type="account",
    name="Acme Corp",
)

# Fire an event
event = client.create_event(
    event_type="invoice.overdue",
    entity_id=entity.entity_id,
    data={"amount": 1200, "days_overdue": 7},
)

Authentication

All API requests require authentication. Use an API key in the Authorization header:

Authorization: Bearer em_live_your_api_key_here

Create API keys in the Console under Settings → API Keys.