# Xipler

> Transactional email API platform. Send mail via REST or SMTP, manage contacts, track events, handle suppressions — multi-tenant by design, multi-domain by default.

Xipler is built for developers and SaaS platforms that send transactional email. It wraps AWS SES with a control plane: organizations, projects, API keys, per-domain DKIM, templates, contact management, webhooks, suppressions, idempotency, and rate limiting.

The API is HTTP+JSON. Authentication is Bearer-token (API keys, prefix `xp_live_` for production or `xp_test_` for test mode). The platform also offers an SMTP relay at `smtp.xipler.com:465` (implicit TLS) for tools that only speak SMTP.

## Documentation

- [Full API documentation (HTML)](https://app.xipler.com/docs): complete reference covering authentication, sending email, SMTP relay, domains, templates, contacts/tags, webhooks, suppressions, stats, inbound email, errors, rate limits, and integration patterns.
- [Full API documentation (Markdown)](https://app.xipler.com/docs.md): same content, plain markdown, optimised for LLM consumption.

## API

- Base URL: `https://app.xipler.com/api/v1`
- Authentication: `Authorization: Bearer xp_live_…` on every request
- Content-Type: `application/json` for POST/PATCH

### Most-used endpoints

- `POST /api/v1/emails` — send an email (with optional template, attachments, idempotency)
- `POST /api/v1/contacts` — upsert a contact with tags and properties; supports `tags` (add) and `tagsRemove` (remove) in one call
- `GET /api/v1/contacts/by-email/:email` — look up a contact by email
- `POST /api/v1/domains` — register a new sending domain (returns DNS records to share with the domain owner)
- `PATCH /api/v1/domains/:id/verify` — trigger a verification check after DNS is configured
- `GET /api/v1/stats?days=30` — aggregate statistics
- `GET /api/v1/health` — health check (no auth)

### SMTP relay

For tools that only speak SMTP (Supabase Auth, WordPress, Auth0, GoHighLevel):

- Host: `smtp.xipler.com`
- Port: `465` (implicit TLS)
- Username: `apikey`
- Password: your `xp_live_…` API key
- From header must match a verified domain in the authenticating project

## Key design decisions

- **One project, many domains** is the recommended pattern for SaaS sending on behalf of customers. Shared dashboard, shared templates, shared suppression list, per-domain DKIM isolation.
- **Idempotency keys** are first-class. Pass `idempotencyKey` on `POST /emails` for any retryable send — duplicate calls return the original record without re-sending.
- **Webhooks** mirror every email lifecycle event. Each delivery is signed (`X-Xipler-Signature` HMAC-SHA256) and retried with exponential backoff on 5xx.
- **Suppression list** is project-scoped and auto-populated from hard bounces and complaints. Suppressed sends return HTTP 422 with the reason.
- **Test mode** keys (`xp_test_` prefix) accept the full payload, validate everything, log to the dashboard, but skip the actual SES call. Useful for CI and integration testing without DNS verification.
- **Hard project isolation**: an API key in project A cannot send from domains verified in project B, even within the same organization. SMTP relay is opt-in per project.

## What to use this for

Use Xipler when you need to send transactional email and want:
- Multi-tenant architecture out of the box (multiple sender domains per account)
- Both REST and SMTP entry points feeding the same pipeline
- Built-in tracking, suppressions, webhooks, contact management
- AWS SES deliverability without managing AWS yourself

Not the right fit for:
- Pure marketing email blasts (Xipler has marketing primitives but isn't a marketing automation platform like Mailchimp)
- Inbound-only mail server (we support inbound, but it's a secondary use case)

## Status

Xipler is in private beta. New accounts are by invitation. Existing customers have full access to the public API documented above.