API Triggers for Custom Automations — Wiring AcelleMail to Anything

The custom-event API and adjacent endpoints in detail.

Authentication:

Authorization: Bearer <token>

Tokens are issued per-account; rotate them when team members leave. Scope-per-integration is recommended — separate tokens for crm-bridge, shopify-webhook, support-tool-sync — so a leak from one source rotates without cascading.

Fire a custom event:

curl -X POST "https://acellemail.com/api/v1/events" \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Event-ID: $(uuidgen)" \
  -d '{
    "subscriber_email": "user@example.com",
    "event": "onboarding_step_3",
    "data": {
      "step_name": "added_first_team_member",
      "duration_seconds": 45,
      "completed_at": "2026-05-19T14:30:00Z"
    },
    "upsert": true
  }'

Response (200 OK):

{
  "event_id": "evt_a1b2c3...",
  "subscriber_uid": "sub_x9y8z7...",
  "automation_runs_triggered": ["auto_onboarding_3_nudge"],
  "processed_at": "2026-05-19T14:30:01Z"
}

The X-Event-ID header is for idempotency — if your bridge retries on timeout, repeated calls with the same event-id are deduplicated server-side.

Batch events (for high-volume backfill):

curl -X POST "https://acellemail.com/api/v1/events/batch" \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"subscriber_email": "a@example.com", "event": "purchase", "data": {...}},
      {"subscriber_email": "b@example.com", "event": "purchase", "data": {...}},
      {"subscriber_email": "c@example.com", "event": "purchase", "data": {...}}
    ]
  }'

Max 1000 events per batch. Useful for backfilling historical events when first integrating a CRM into AcelleMail.

Webhook signing (when AcelleMail webhooks out to your system):

If you configure AcelleMail to Send webhook as an automation step, AcelleMail signs every outbound request with an HMAC-SHA256 header:

X-AcelleMail-Signature: t=1684320000,v1=abc123def456...

Verify on your side:

import hmac, hashlib, time

def verify_webhook(body, signature_header, secret):
    parts = dict(p.split('=') for p in signature_header.split(','))
    timestamp = parts['t']
    sig = parts['v1']
    payload = f"{timestamp}.{body}".encode()
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Reject any request older than 5 minutes (replay protection) and verify the signature matches — this prevents anyone-with-the-URL from forging requests.

Retries:

AcelleMail's outbound webhooks retry with exponential backoff on 5xx responses: 1m, 5m, 30m, 2h, 12h, 24h. After 6 failed attempts the webhook is marked failed-permanent and the automation step's run shows red.

For inbound events FROM your system, you control retries — if AcelleMail returns 5xx, retry with exponential backoff. Don't retry on 4xx (bad payload — retrying won't fix it).

SDK examples:

// Node.js
const fetch = require('node-fetch');

async function fireEvent(email, event, data) {
  const res = await fetch('https://acellemail.com/api/v1/events', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ACELLE_TOKEN}`,
      'Content-Type': 'application/json',
      'X-Event-ID': crypto.randomUUID(),
    },
    body: JSON.stringify({
      subscriber_email: email,
      event,
      data,
      upsert: true,
    }),
  });
  if (!res.ok) throw new Error(`AcelleMail event failed: ${res.status}`);
  return res.json();
}

// Usage:
await fireEvent('user@example.com', 'onboarding_step_3', {
  step_name: 'added_first_team_member',
});

# Python
import requests, uuid, os

def fire_event(email, event, data):
    res = requests.post(
        'https://acellemail.com/api/v1/events',
        headers={
            'Authorization': f"Bearer {os.environ['ACELLE_TOKEN']}",
            'Content-Type': 'application/json',
            'X-Event-ID': str(uuid.uuid4()),
        },
        json={
            'subscriber_email': email,
            'event': event,
            'data': data,
            'upsert': True,
        },
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

# Usage:
fire_event('user@example.com', 'onboarding_step_3', {
    'step_name': 'added_first_team_member'
})

// PHP / Laravel
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

function fireAcelleEvent(string $email, string $event, array $data): array
{
    $response = Http::withToken(config('services.acelle.token'))
        ->withHeaders(['X-Event-ID' => (string) Str::uuid()])
        ->timeout(10)
        ->post('https://acellemail.com/api/v1/events', [
            'subscriber_email' => $email,
            'event' => $event,
            'data' => $data,
            'upsert' => true,
        ]);

    $response->throw();
    return $response->json();
}

// Usage:
fireAcelleEvent('user@example.com', 'onboarding_step_3', [
    'step_name' => 'added_first_team_member',
]);

Local development testing — use webhook.site or ngrok to expose your local dev server to AcelleMail's webhook deliveries while developing:

ngrok http 3000
# AcelleMail webhook URL: https://<ngrok-id>.ngrok.io/your-endpoint

Update the automation's webhook destination during dev; flip back to your production URL when shipping.

Rate limits:

The events API accepts 1000 requests/minute per token. Burst higher than that returns 429 with Retry-After header — back off and retry. For high-volume systems, use the batch endpoint instead.

Schema versioning:

If your event payload schema changes (e.g. you rename data.product to data.sku), bump the event name explicitly: purchase_completed → purchase_completed_v2. AcelleMail automations target one event name; switching is opt-in per-automation, so old data and new data don't crash each other.

Audit trail:

Every API call to /api/v1/events is logged in AcelleMail's audit log (admin → Audit log). Useful for forensics when a bug fires unexpected events — search by token, by event name, by subscriber email.