Xipler API Documentation

Two prefixes signal two different runtime behaviors:

• xp_live_ — production. Real emails delivered via SES.
• xp_test_ — test mode. Email is fully validated and logged in the dashboard but never handed to SES. Domain verification is skipped, so you can wire integrations before any DNS is configured.

Each key has a set of permissions (currently send and read). Sending endpoints require send; read endpoints accept either. A missing permission returns:

{ "error": "API key does not have 'send' permission" }

Keys are stored as SHA-256 hashes. The plaintext is shown once at creation and never displayed again. Lost a key — generate a new one and delete the old. Revocation propagates within 5 minutes (the in-memory cache TTL).

• to — string or "Name <email>". Required.
• from — must match a verified domain in the project. If omitted, the project default sender is used.
• subject — max 500 chars. Required.
• html or text — at least one required. Plaintext is auto-generated from HTML if not provided.
• template — slug of a stored template. {{variable}} placeholders in the template are filled from data.
• attachments — max 10. Use content (base64) for local files or path (HTTPS URL) for remote.
• scheduledAt — ISO 8601 datetime in the future. Email is queued, not sent immediately.
• idempotencyKey — string, max 255 chars. Replays with the same key return the original record without re-sending. Strongly recommended for user-facing mail.
• track_opens / track_clicks — override the project-level tracking defaults per call.

json
{
  "id": "f8a1c4e2-...",
  "status": "queued",
  "from": "noreply@yourdomain.com",
  "to": "user@example.com"
}

The id is the canonical email identifier. Use it to look up the email later or correlate with webhook events.

Returns up to 100 emails. Query params:

• limit — max 100, default 50
• offset — pagination offset
• status — filter by status

Returns the email row + all tracked events (sent, delivered, opened, clicked, bounced, complained).

Cancels a queued or scheduled email. Already-sent emails cannot be unsent.

Send up to 100 emails in one request. Body is { "emails": [...] } where each item follows the single-email schema above. Returns per-email results.

javascript
import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.xipler.com",
  port: 465,
  secure: true,  // implicit TLS, NOT STARTTLS
  auth: {
    user: "apikey",
    pass: process.env.XIPLER_API_KEY,
  },
});

await transport.sendMail({
  from: '"Your Company" <noreply@yourdomain.com>',
  to: "user@example.com",
  subject: "Hello",
  html: "<p>Sent via SMTP</p>",
});

In the Supabase dashboard → Authentication → Email Templates → SMTP Settings:

Sender email:   noreply@yourdomain.com
Host:           smtp.xipler.com
Port:           465
Username:       apikey
Password:       xp_live_xxxxx

• SMTP is opt-in per project. Enable in Project Settings → SMTP Relay.
• The From: header must match a verified domain in the authenticating project.
• Suppressed recipients are rejected at RCPT TO with 550 5.1.1.
• Hard project isolation — a key for project A cannot send from domains verified in project B.

json
{ "domain": "customer.com" }

Response:

json
{
  "domain": {
    "id": "dom_a1b2c3...",
    "domain": "customer.com",
    "status": "pending",
    "dkimTokens": ["abc...", "def...", "ghi..."],
    "mailFromDomain": "bounce.customer.com",
    "dnsRecords": [
      { "type": "CNAME", "name": "abc._domainkey.customer.com",
        "value": "abc.dkim.amazonses.com" },
      { "type": "CNAME", "name": "def._domainkey.customer.com",
        "value": "def.dkim.amazonses.com" },
      { "type": "CNAME", "name": "ghi._domainkey.customer.com",
        "value": "ghi.dkim.amazonses.com" },
      { "type": "MX",    "name": "bounce.customer.com",
        "value": "feedback-smtp.eu-central-1.amazonses.com",
        "priority": 10 },
      { "type": "TXT",   "name": "bounce.customer.com",
        "value": "v=spf1 include:amazonses.com ~all" }
    ]
  }
}

Display these records to the domain owner. They'll add them at their DNS provider.

Forces a live re-check with AWS SES + DNS. Returns updated status. The status reaches verified once DKIM is confirmed.

Alternative: subscribe to the domain.verified webhook event for passive monitoring.

Returns all domains (or one) with their DNS records.

Removes the domain from Xipler and AWS SES. Fires domain.deleted webhook.

json
{
  "name": "Session Reminder",
  "slug": "session-reminder",
  "subject": "Reminder: your session with {{coachName}}",
  "html": "<p>Hi {{clientName}}, your session is on {{sessionDate}}.</p>",
  "variables": ["coachName", "clientName", "sessionDate"]
}

json
{
  "to": "client@example.com",
  "template": "session-reminder",
  "data": {
    "coachName": "Janneke",
    "clientName": "Pieter",
    "sessionDate": "20 May 2026"
  }
}

Idempotent upsert by email. Tags are auto-created if they don't exist.

json
{
  "email": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "source": "trial-signup",
  "tags": ["trial"],
  "tagsRemove": ["lead"],
  "properties": {
    "plan": "trial",
    "trial_started_at": "2026-05-18T12:00:00Z"
  }
}

• tags — add (idempotent). Tag names not yet in the project are created automatically.
• tagsRemove — remove these tag names from this contact. Useful for flipping trial → paid in one call.
• properties — flexible key/value, string/number/boolean/null only.

Trial signup → tag trial:

javascript
fetch("https://app.xipler.com/api/v1/contacts", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    email: user.email,
    firstName: user.firstName,
    tags: ["trial"],
    properties: { plan: "trial", trial_started_at: new Date().toISOString() },
  }),
});

Convert trial → paid (one call):

javascript
fetch("https://app.xipler.com/api/v1/contacts", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    email: user.email,
    tags: ["paid"],
    tagsRemove: ["trial"],
    properties: { plan: "paid", converted_at: new Date().toISOString() },
  }),
});

Use by-email for the common case of finding a contact you only have the email for. Returns 404 if not found.

Update first/last name, status, properties. For tag changes prefer the upsert endpoint.

Permanent. Fires contact.deleted webhook.

Useful when you don't want a full upsert. POST accepts tagId or tagName in the body. DELETE requires the tag id.

Returns custom events tracked for the contact (page views, button clicks, anything you ingest).

Tags are usually auto-created via POST /contacts. Explicit creation is only needed when you want to set a color or description.

Read-only via the public API. Lists are managed in the dashboard.

json
{
  "event": "delivered",
  "timestamp": "2026-05-18T10:23:45Z",
  "data": {
    "emailId": "f8a1c4e2-...",
    "projectId": "9bbb241c-...",
    "to": "user@example.com",
    "from": "noreply@yourdomain.com",
    "messageId": "0100018f-...",
    "metadata": {
      "smtpResponse": "250 2.6.0 ...",
      "processingTimeMs": 423
    }
  }
}

Each request carries headers:

X-Xipler-Signature: sha256=<hex digest>
X-Xipler-Event: delivered
X-Xipler-Timestamp: 2026-05-18T10:23:45Z

Verify in Node.js:

javascript
import crypto from "crypto";

function verifyWebhook(rawBody, headerSig, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(headerSig),
    Buffer.from(expected)
  );
}

Compute against the raw bytes, not parsed JSON.

On 5xx or timeout, Xipler retries with exponential backoff: 1s, 2s, 4s (up to 3 attempts). Return 2xx quickly; do any heavy work async on your side.

json
{ "error": "Human-readable description of what went wrong" }

Pass an idempotencyKey string (max 255 chars) on POST /emails. Subsequent requests with the same key + project return the original record without re-sending. Strongly recommended for any retry-able send.

Standard per-API-key limits apply. Excess requests return 429 with a Retry-After header. Use exponential backoff on retries. SMTP relay has separate per-project limits configurable in project settings.

Most common pattern. Your platform sends emails from the customer's domain so end-users see noreply@customer.com in their inbox, not your platform's domain.

Setup:

• One Xipler project for the whole SaaS
• One API key stored in your environment
• N domains — one per customer, added via API as customers sign up
• Project setting allowApiFromOverride: true so the from field can vary per call

Customer signup flow:

javascript
// 1. Customer enters their domain in your UI
const res = await fetch("https://app.xipler.com/api/v1/domains", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ domain: customerDomain }),
});
const { domain } = await res.json();

// 2. Show domain.dnsRecords to the customer with copy buttons.
//    Save domain.id linked to your customer record.

// 3. When customer claims DNS is set, trigger verification:
await fetch(`https://app.xipler.com/api/v1/domains/${domain.id}/verify`, {
  method: "PATCH",
  headers: { Authorization: `Bearer ${KEY}` },
});
// OR subscribe to the 'domain.verified' webhook

// 4. Once verified, send from their domain:
await fetch("https://app.xipler.com/api/v1/emails", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    to: endUser.email,
    from: `noreply@${customer.domain}`,
    template: "...",
    data: { ... },
    idempotencyKey: `notification-${eventId}`,
  }),
});

Use the from field on each webhook event to attribute bounces back to the right customer.

When each customer needs their own dashboard, suppression list, and stats (white-label use cases). Each customer = one Xipler project = one API key. More operational overhead — use only when isolation matters more than convenience.

Use two projects: Transactional and Marketing. Different keys, different suppression lists. Marketing bounces don't block future transactional mail to the same address.