API Reference

Quick Start

npm install @sendinel/sdk

import { Sendinel } from "@sendinel/sdk";

const sendinel = new Sendinel({ apiKey: "snk_..." });

// Identify a user — creates or updates their contact profile
await sendinel.identify("user@example.com", {
  firstName: "Alex",
  properties: { plan: "pro" },
  siteId: "your-site-uuid",   // subscribes them + triggers signup campaigns
});

// Fire a named event — triggers any matching campaign automations
await sendinel.track("user@example.com", "completed_onboarding");

curl -X POST https://sendinel.ai/api/v1/identify \
  -H "Authorization: Bearer snk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "Alex",
    "properties": { "plan": "pro" },
    "site_id": "your-site-uuid"
  }'

TypeScript SDK

npm install @sendinel/sdk

import { Sendinel, SendinelError } from "@sendinel/sdk";

const sendinel = new Sendinel({
  apiKey: process.env.SENDINEL_API_KEY!,
  // baseUrl: "https://sendinel.ai"  // default, override for self-hosted
});

// Identify — creates or updates a contact profile (idempotent by email)
const { contact_id, created } = await sendinel.identify("alex@example.com", {
  firstName: "Alex",
  lastName: "Smith",
  properties: { plan: "pro", company: "Acme" },
  tags: ["paying", "enterprise"],
  siteId: "your-site-uuid",  // subscribes to site + enrolls in signup campaigns
});

// Track — fires a named event, auto-creates contact if needed
const result = await sendinel.track("alex@example.com", "completed_onboarding", {
  steps_completed: 5,
  duration_seconds: 142,
});
// result.enrolled_campaigns  →  ["Welcome to Pro"]
// result.contact_created     →  false (contact already existed)

// Send — transactional email, one-off
await sendinel.send({
  to: "alex@example.com",
  siteId: "your-site-uuid",
  subject: "Your order is confirmed",
  html: "<p>Order #123 ships tomorrow.</p>",
  idempotencyKey: "order-123",  // prevents duplicate sends
});

import { Sendinel, SendinelError } from "@sendinel/sdk";

try {
  await sendinel.identify("bad-email");
} catch (err) {
  if (err instanceof SendinelError) {
    console.log(err.status);  // 400
    console.log(err.message); // "Invalid email address"
    console.log(err.body);    // full JSON response
  }
}

Identify API

{
  "email": "user@example.com",       // required
  "first_name": "Alex",              // optional
  "last_name": "Smith",              // optional
  "properties": {                    // optional — merged (patch semantics, never overwrites)
    "plan": "pro",
    "company": "Acme"
  },
  "tags": ["paying", "enterprise"],  // optional — appended, no duplicates
  "site_id": "uuid"                  // optional — subscribes to site + triggers signup campaigns
}

{
  "contact_id": "uuid",
  "created": true
}

{
  "contact_id": "uuid",
  "created": false
}

curl -X POST https://sendinel.ai/api/v1/identify \
  -H "Authorization: Bearer snk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@acme.com",
    "first_name": "Alex",
    "properties": { "plan": "pro", "source": "stripe" },
    "tags": ["paying"],
    "site_id": "your-site-uuid"
  }'

const { contact_id, created } = await sendinel.identify("alex@acme.com", {
  firstName: "Alex",
  properties: { plan: "pro", source: "stripe" },
  tags: ["paying"],
  siteId: "your-site-uuid",
});

Events API

{
  "email": "user@example.com",          // required
  "event": "completed_onboarding",      // required — must match a campaign trigger_event_name
  "data": { "steps_completed": 5 }      // optional — stored in event metadata
}

{
  "event": "completed_onboarding",
  "contact_id": "uuid",
  "contact_created": false,              // true if contact was auto-created
  "enrollments_created": 1,
  "enrolled_campaigns": ["Onboarding Sequence"],
  "skipped_campaigns": []               // already enrolled in these
}

curl -X POST https://sendinel.ai/api/v1/events \
  -H "Authorization: Bearer snk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex@acme.com",
    "event": "completed_onboarding",
    "data": { "steps_completed": 5 }
  }'

const result = await sendinel.track("alex@acme.com", "completed_onboarding", {
  steps_completed: 5,
});

console.log(result.enrolled_campaigns); // ["Onboarding Sequence"]
console.log(result.contact_created);    // false

Transactional Email API

{
  "to": "user@example.com",             // required — recipient email
  "site_id": "uuid",                     // required — identifies sender domain + from address
  "subject": "Order confirmed",          // required — max 998 characters
  "html": "<p>Your order #123...</p>",   // required — HTML body
  "text": "Your order #123...",          // optional — plain text fallback
  "reply_to": "support@company.com",    // optional
  "headers": { "X-Custom": "value" },   // optional — custom headers
  "tags": ["transactional", "order"],   // optional — for filtering in email log
  "idempotency_key": "order-123",        // optional — prevents duplicate sends
  "tracking": true                       // optional — default true (open + click tracking)
}

{
  "id": "uuid",                          // Sendinel email log ID
  "provider_message_id": "re_xxxx",     // Resend (or provider) message ID
  "to": "user@example.com",
  "status": "sent"
}

curl -X POST https://sendinel.ai/api/v1/send \
  -H "Authorization: Bearer snk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "alex@acme.com",
    "site_id": "your-site-uuid",
    "subject": "Your order is confirmed",
    "html": "<h1>Order #123</h1><p>Ships tomorrow.</p>",
    "idempotency_key": "order-123"
  }'

await sendinel.send({
  to: "alex@acme.com",
  siteId: "your-site-uuid",
  subject: "Your order is confirmed",
  html: "<h1>Order #123</h1><p>Ships tomorrow.</p>",
  idempotencyKey: "order-123",
});

Conversion Tracking

{
  "email": "user@example.com",       // required
  "event": "purchase",               // optional — default: "purchase"
  "revenue": 49.99,                  // optional
  "currency": "USD",                 // optional — default: "USD"
  "order_id": "order_123",           // optional — deduplication key (409 on duplicate)
  "metadata": { "plan": "pro" }      // optional
}

{
  "id": "uuid",
  "contact_id": "uuid",
  "email_log_id": "uuid",
  "campaign_id": "uuid",
  "event": "purchase",
  "revenue": 49.99,
  "attributed_at": "2026-04-10T12:00:00Z"
}

Webhooks

https://sendinel.ai/api/webhooks/resend

https://sendinel.ai/api/webhooks/resend/[projectId]

MCP Integration

AI Clients

{
  "mcpServers": {
    "sendinel": {
      "type": "sse",
      "url": "https://sendinel.ai/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer snk_your_api_key"
      }
    }
  }
}

{
  "mcpServers": {
    "sendinel": {
      "command": "npx",
      "args": ["@sendinel/mcp-server"],
      "env": {
        "SUPABASE_URL": "https://xxx.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key",
        "SENDINEL_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

{
  "mcpServers": {
    "sendinel": {
      "type": "sse",
      "url": "https://sendinel.ai/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer snk_your_api_key"
      }
    }
  }
}

npx @sendinel/mcp-setup --install-skill

{
  "mcp": {
    "servers": {
      "sendinel": {
        "url": "https://sendinel.ai/api/mcp/sse",
        "headers": {
          "Authorization": "Bearer snk_your_api_key"
        }
      }
    }
  }
}

[[mcp_servers]]
name = "sendinel"
transport = "sse"
url = "https://sendinel.ai/api/mcp/sse"

[mcp_servers.headers]
Authorization = "Bearer snk_your_api_key"

// Your prompt:
"List my active campaigns and tell me which ones have the lowest open rates."

// Agent calls:
list_campaigns({ "status": "active" })
get_stats({ "campaign_id": "uuid", "period": "30d" })

// Returns:
{
  "campaigns": [
    { "name": "Welcome Series", "open_rate": 0.42, "enrolled": 142 },
    { "name": "Re-engagement",  "open_rate": 0.11, "enrolled": 38 }
  ]
}

Rate Limits

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1744329600

Error Codes

{
  "error": "Descriptive error message",
  "code": "SUPPRESSED_CONTACT",   // optional — machine-readable code
  "details": { ... }              // optional — additional context
}

Need help? support@sendinel.ai