Developer Reference

API Documentation

Send emails, manage contacts, verify domains, and track delivery programmatically. Authenticate with your API key and call /api/v1 endpoints.

Emails Contacts Domains Webhooks Campaigns Stats

Authentication

All API requests require a Bearer token. Generate your API key from Settings → Security in your dashboard.

# Include in every request header:
Authorization: Bearer sk_live_your_api_key_here

# Base URL:
https://your-app.com/api/v1/

# Rate limits:
# Starter: 100 req/min | Professional: 500 req/min | Enterprise: 2000 req/min

Keep your API key secret. Never expose it in client-side code. If compromised, revoke it immediately from Settings.

Webhook Verification

All webhook payloads are signed with HMAC-SHA256. Verify the signature to ensure authenticity.

// Node.js webhook verification
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  if (!verifyWebhook(JSON.stringify(req.body), sig, SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const { type, data } = req.body;
  // Process event...
  res.status(200).send('OK');
});

Available events

email.sentemail.deliveredemail.openedemail.clickedemail.bouncedemail.complained

Emails

POST/api/v1/emails

Send a transactional email

Request

curl -X POST https://your-app.com/api/v1/emails \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "you@yourdomain.com",
    "subject": "Welcome!",
    "html": "<h1>Hello!</h1><p>Welcome aboard.</p>",
    "tags": { "type": "welcome" }
  }'

Response

{
  "id": "clx1234...",
  "status": "sent",
  "messageId": "ses-message-id"
}

POST/api/v1/emails/batch

Send up to 100 emails in one request

Request

curl -X POST https://your-app.com/api/v1/emails/batch \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      { "to": "a@example.com", "from": "you@domain.com", "subject": "Hi", "html": "<p>Hello A</p>" },
      { "to": "b@example.com", "from": "you@domain.com", "subject": "Hi", "html": "<p>Hello B</p>" }
    ]
  }'

Response

{
  "results": [
    { "to": "a@example.com", "id": "clx...", "status": "sent" },
    { "to": "b@example.com", "id": "clx...", "status": "sent" }
  ],
  "total": 2, "sent": 2, "failed": 0
}

GET/api/v1/emails

List email logs with pagination

Request

curl "https://your-app.com/api/v1/emails?limit=20&status=sent" \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "emails": [{ "id": "...", "to": "...", "subject": "...", "status": "sent", "opens": 3 }],
  "total": 150, "page": 1, "pages": 8
}

GET/api/v1/emails/:id

Get email details with all events

Request

curl https://your-app.com/api/v1/emails/clx1234 \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "email": { "id": "...", "to": "...", "status": "sent", "opens": 5, "clicks": 2 },
  "events": [{ "type": "sent", "createdAt": "..." }, { "type": "opened", "createdAt": "..." }]
}

Contacts

POST/api/v1/contacts

Create a new contact

Request

curl -X POST https://your-app.com/api/v1/contacts \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "new@example.com", "name": "John Doe", "listId": "list_id" }'

Response

{ "id": "...", "email": "new@example.com", "name": "John Doe", "status": "subscribed" }

GET/api/v1/contacts

List contacts with pagination and filtering

Request

curl "https://your-app.com/api/v1/contacts?limit=50&listId=..." \
  -H "Authorization: Bearer sk_live_your_key"

Response

{ "contacts": [...], "total": 1000, "page": 1 }

Domains

GET/api/v1/domains

List verified domains

Request

curl https://your-app.com/api/v1/domains \
  -H "Authorization: Bearer sk_live_your_key"

Response

{ "domains": [{ "domain": "yourdomain.com", "status": "verified" }] }

POST/api/v1/domains/:id/verify

Trigger domain verification

Request

curl -X POST https://your-app.com/api/v1/domains/dom_id/verify \
  -H "Authorization: Bearer sk_live_your_key"

Response

{ "status": "verified", "domain": "yourdomain.com" }

Webhooks

POST/api/v1/webhooks

Create a webhook endpoint

Request

curl -X POST https://your-app.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["email.sent", "email.opened", "email.clicked", "email.bounced"]
  }'

Response

{
  "id": "...",
  "url": "https://your-app.com/webhook",
  "secret": "whsec_...",
  "events": ["email.sent", "email.opened", "email.clicked", "email.bounced"]
}

GET/api/v1/webhooks

List all configured webhooks

Request

curl https://your-app.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_key"

Response

{ "webhooks": [{ "id": "...", "url": "...", "events": [...], "isActive": true }] }

Campaigns

POST/api/v1/campaigns

Create a campaign

Request

curl -X POST https://your-app.com/api/v1/campaigns \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "March Newsletter", "subject": "News!", "listId": "...", "content": "<h1>Hello</h1>" }'

Response

{ "id": "...", "name": "March Newsletter", "status": "draft" }

POST/api/v1/campaigns/:id/launch

Launch a campaign to start sending

Request

curl -X POST https://your-app.com/api/v1/campaigns/camp_id/launch \
  -H "Authorization: Bearer sk_live_your_key"

Response

{ "success": true, "status": "sending" }

Stats

GET/api/v1/stats

Get account statistics

Request

curl https://your-app.com/api/v1/stats \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "contacts": 1500,
  "campaigns": { "total": 45, "sending": 1, "completed": 40 },
  "emailsThisMonth": 12500,
  "domains": 2
}

Ready to integrate?

Generate your API key from the dashboard and start sending emails in minutes. SDKs for Node.js, Python, and Go are coming soon.

Get your API key

# Include in every request header: Authorization: Bearer sk_live_your_api_key_here # Base URL: https://your-app.com/api/v1/ # Rate limits: # Starter: 100 req/min | Professional: 500 req/min | Enterprise: 2000 req/min

// Node.js webhook verification const crypto = require('crypto'); function verifyWebhook(body, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(body) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } // In your webhook handler: app.post('/webhook', (req, res) => { const sig = req.headers['x-webhook-signature']; if (!verifyWebhook(JSON.stringify(req.body), sig, SECRET)) { return res.status(401).send('Invalid signature'); } const { type, data } = req.body; // Process event... res.status(200).send('OK'); });

curl -X POST https://your-app.com/api/v1/emails \ -H "Authorization: Bearer sk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "from": "you@yourdomain.com", "subject": "Welcome!", "html": "<h1>Hello!</h1><p>Welcome aboard.</p>", "tags": { "type": "welcome" } }'

curl -X POST https://your-app.com/api/v1/emails/batch \ -H "Authorization: Bearer sk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "emails": [ { "to": "a@example.com", "from": "you@domain.com", "subject": "Hi", "html": "<p>Hello A</p>" }, { "to": "b@example.com", "from": "you@domain.com", "subject": "Hi", "html": "<p>Hello B</p>" } ] }'

curl -X POST https://your-app.com/api/v1/contacts \ -H "Authorization: Bearer sk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "email": "new@example.com", "name": "John Doe", "listId": "list_id" }'

curl -X POST https://your-app.com/api/v1/webhooks \ -H "Authorization: Bearer sk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhook", "events": ["email.sent", "email.opened", "email.clicked", "email.bounced"] }'

curl -X POST https://your-app.com/api/v1/campaigns \ -H "Authorization: Bearer sk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "name": "March Newsletter", "subject": "News!", "listId": "...", "content": "<h1>Hello</h1>" }'