Hello
", "text": "Hello (plain text fallback)", "headers": { "X-Custom-Header": "value" }, "template": "session-reminder", "data": { "name": "Janneke", "date": "16 May" }, "tags": ["transactional"], "attachments": [ { "filename": "invoice.pdf", "content": "Sent via SMTP
", }); ``` ### Example: Supabase Auth ``` Sender email: noreply@yourdomain.com Host: smtp.xipler.com Port: 465 Username: apikey Password: xp_live_xxxxx ``` ### Rules - 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. --- ## Domains Before sending from a domain, it must be registered and its DNS verified. Xipler auto-generates the required DKIM, MAIL FROM, and SPF records. ### POST /api/v1/domains ```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. ### Other domain endpoints ``` GET /api/v1/domains List all GET /api/v1/domains/:id One domain + DNS records PATCH /api/v1/domains/:id/verify Force a verification re-check DELETE /api/v1/domains/:id Remove (also unregisters in SES) ``` `domain.verified` and `domain.created`/`domain.deleted` webhook events fire automatically. --- ## Templates Templates are HTML fragments with `{{variable}}` placeholders. ### POST /api/v1/templates ```json { "name": "Session Reminder", "slug": "session-reminder", "subject": "Reminder: your session with {{coachName}}", "html": "Hi {{clientName}}, your session is on {{sessionDate}}.
", "variables": ["coachName", "clientName", "sessionDate"] } ``` ### Use in a send ```json { "to": "client@example.com", "template": "session-reminder", "data": { "coachName": "Janneke", "clientName": "Pieter", "sessionDate": "20 May 2026" } } ``` ### Other template endpoints ``` GET /api/v1/templates List GET /api/v1/templates/:slug One DELETE /api/v1/templates/:slug Remove ``` --- ## Contacts & tags Contacts are people you can reach — typically your customers or their end-users. Tags are labels for segmentation and automations. Lists are explicit mailing-list memberships. ### POST /api/v1/contacts (upsert) 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. ### Common scenarios **Trial signup → `trial` tag:** ```javascript await 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 await 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() }, }), }); ``` ### Lookup endpoints ``` GET /api/v1/contacts List (paginated, ?status=) GET /api/v1/contacts/:id One contact + tags + lists GET /api/v1/contacts/by-email/:email Lookup by email (URL-encoded) ``` ### Other contact endpoints ``` PATCH /api/v1/contacts/:id Update name, status, properties DELETE /api/v1/contacts/:id GDPR delete POST /api/v1/contacts/:id/tags Add a single tag (by id or name) DELETE /api/v1/contacts/:id/tags/:tagId Remove tag (requires tag id) GET /api/v1/contacts/:id/events Contact event history ``` ### Tags ``` GET /api/v1/tags List POST /api/v1/tags Create (with color, description) DELETE /api/v1/tags/:id Delete (also unlinks from all contacts) ``` Tags are usually auto-created via `POST /contacts`. Explicit creation is only needed when setting a custom color or description. ### Lists ``` GET /api/v1/lists List mailing lists (managed in dashboard) ``` --- ## Webhooks Configure per project in the dashboard. Xipler POSTs JSON to your URL when subscribed events fire. ### Event types | Event | Trigger | |---|---| | `sent` | Email accepted by SES | | `delivered` | Delivered to recipient | | `opened` | Tracking pixel loaded | | `clicked` | Tracked link clicked | | `bounced` | Soft or hard bounce | | `complained` | Spam complaint | | `failed` | Send failed | | `email.received` | Inbound email arrived | | `contact.created` | Contact created | | `contact.updated` | Contact updated | | `contact.deleted` | Contact deleted | | `domain.created` | Domain registered | | `domain.verified` | Domain DKIM verified | | `domain.deleted` | Domain removed | ### Payload shape ```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 } } } ``` ### Signature verification Each request carries: ``` X-Xipler-Signature: sha256=