# Ranla — full documentation bundle

Generated for AI agents. Canonical index: https://docs.ranla.ai/llms.txt
OpenAPI: https://docs.ranla.ai/openapi.yaml

---
<!-- canonical: https://docs.ranla.ai/what-is-ranla -->

# What is Ranla

Ranla is the AI growth engineer. It runs the marketing across six jobs from what people do in your product, and ships the product events and conversion tracking it needs as pull requests you review. Transactional email runs on the same stack.

You talk to Ranla in the app, in Slack, or from Cursor and Claude over [MCP](./ai/mcp.md). Each job has a desk in the app where you see what Ranla found, what it drafted, and what is waiting on you.

## The six jobs

| Job | What Ranla does | What you connect | How-to |
|-----|-----------------|------------------|--------|
| **Engineering** | Writes the product events and conversion tracking the other jobs need, as a pull request you review. It does not push to your default branch. | GitHub, or send events with the SDK | [Instrument your product](./instrument-quickstart.md) |
| **Lifecycle email** | Campaigns and automations for activation, trial endings, and win-backs, with a holdout when you want proof of lift. Transactional email and SMS run on the same stack. | A verified sending domain. SMS uses your own Twilio account. | [Automations](./api/automations.md) |
| **Paid advertising** | Drafts ads and landing angles, watches spend against the goals you named, and recommends pausing what does not earn. Google Ads today. | Google Ads. Google bills ad spend to your own card. | [Google Ads](./guides/google-ads.md) |
| **Search** | Finds the queries your buyers actually run, drafts pages that answer them, and tracks whether they rank. | Google Search Console. GitHub to deliver pages as pull requests. | [Search](./guides/seo.md) |
| **AEO** | Tracks whether answer engines cite you, drafts the pages and proof that earn mentions, and reports lift. Google AI Overview, ChatGPT, and Perplexity. | Nothing | — |
| **Social** | Finds threads worth joining, drafts posts and replies in your voice, and schedules what you approve. Reddit today. | Nothing to find threads and draft. Your Reddit account to post. | [Social](./guides/reddit.md) |

## What every job shares

| Part | What it is | How-to |
|------|------------|--------|
| **Events** | The product signals every job reads: signup, activation, billing. Sent through the API, the dashboard, or PostHog, Amplitude, and Mixpanel. | [Events](./guides/events.md) · [Connect analytics](./guides/connect-analytics.md) |
| **Brand** | How your product looks and talks, seeded from your website. Every draft uses it. | [Brand](./guides/brand.md) |
| **Creative** | Images and ad assets composed in your brand style. | [Creative](./guides/creative.md) |
| **Revenue** | Conversions and revenue by channel, from Stripe and Google Ads. | [Revenue](./guides/revenue.md) |
| **On-site messages** | Banners and modals for visitors to your website. | [On-site messages](./guides/on-site-messages.md) |

## How far Ranla acts on its own

You choose a mode on **Settings → Ranla**:

| Mode | What it does |
|------|--------------|
| **Draft** | Nothing sends, spends, publishes, posts, or lands in your repo until you do it. |
| **Propose** | It asks before each email, ad, page, post, or pull request, in the app or Slack. |
| **Autopilot** | It runs inside the limits you set. Big or expensive work still waits. |

The frequency cap and the daily account cap you set are enforced on every send, and any audience over 5,000 people needs your approval in every mode. See [Modes](./guides/modes.md).

## Free and paid plans

| | Free | Paid, from $99/mo |
|---|------|-------------------|
| **Chat with Ranla** | 500 credits a month | 5,000 to 125,000 credits a month |
| **Drafts and proposals in all six jobs** | Yes | Yes |
| **Every desk and report** | Yes | Yes |
| **Pull requests in your repo** | Yes, they use credits | Yes, they use credits |
| **Transactional email** | 3,000 a month, 100 a day, 1 domain | On the same credits as lifecycle email |
| **Sending campaigns and automations** | No | Yes |
| **Autopilot and desks that check in daily** | No | Yes, inside the limits you set |

Every paid plan has every feature; plans differ only in monthly credits. Start on Free and upgrade from **Billing** when you want Ranla to send. See [ranla.ai/pricing](https://ranla.ai/pricing).

## Next steps

- [Instrument your product](./instrument-quickstart.md): connect GitHub (Ranla opens a pull request) or send events with the SDK
- [Quickstart: send email](./quickstart.md): API key, domain DNS, first `POST /emails`
- [Modes](./guides/modes.md): how far Ranla acts on its own
- [MCP server](./ai/mcp.md): work with Ranla from Cursor or Claude
- Product site: [ranla.ai](https://ranla.ai) · Dashboard: [app.ranla.ai](https://app.ranla.ai)

---

<!-- canonical: https://docs.ranla.ai/instrument-quickstart -->

# Instrument your product

Wire Ranla into your SaaS so lifecycle email runs on product data — not only `POST /emails` for password resets.

There are **two ways** to get events into Ranla:

1. **Have Ranla wire it** — Connect GitHub; Ranla inspects your product and opens one pull request for you to review.
2. **Install it yourself** — Add the SDK (or REST) and emit events from your app.

**Only need auth email today?** Skip to [Quickstart: send email](./quickstart.md).

**Marketing site, not product?** That is one line of HTML and a separate install — see [Track your website](#track-your-website).

---

## What you are setting up

| Piece | GitHub path | DIY path |
|-------|-------------|----------|
| Account on [app.ranla.ai](https://app.ranla.ai) | Required | Required |
| GitHub App on your product repo | Required | — |
| Pull request with lifecycle events | Ranla opens it; you merge | — |
| API key + SDK / REST | Often included in the PR | You add it |
| Product events flowing | After you merge and deploy | You call `events.trigger` |
| Verified sending domain | Still needed to send from your brand | Same |
| Growth workspace (hire Ranla) | Optional for campaigns / agent | Same |

Ranla reads events from your app. Campaigns and automations react to those events. Sends go through the same API as transactional mail.

You can use **both** paths: GitHub for the first wiring (or later moments), and the SDK anytime you want to emit an event by hand. You can also [connect analytics](./guides/connect-analytics.md) for moments you already track elsewhere.

---

## Path A — Have Ranla wire it (recommended)

Best when you want Ranla to find the right call sites in your codebase and open a PR. Ranla never pushes to your default branch.

### 1. Open Install Ranla on Home

1. Sign in at [app.ranla.ai](https://app.ranla.ai).
2. Go to **Home** (`/overview`).
3. Expand **Install Ranla** → **Show installation options**.

### 2. Connect GitHub

1. Click **Connect GitHub**.
2. Install the Ranla GitHub App and grant access to the repository that runs your product (not a docs-only or marketing-only repo unless that is where the app code lives).
3. When GitHub is connected, use **Choose a repository** to pick which repo Ranla may read.

Connecting GitHub does **not** require hiring Ranla. You can still send events and use the send API on the free tier.

### 3. Let Ranla inspect and open a PR

In **Growth** (or the agent window after hire), ask Ranla to instrument your product — or continue from the Install Ranla / welcome flow if it already started a scan.

Ranla will:

1. Read the selected repository.
2. Propose lifecycle events (signups, activation, subscription moments, and similar).
3. Open **one pull request** with the wiring for you to review.

You review and merge on GitHub. Deploy as you normally would. After merge, product moments should start showing up in **Events**.

### 4. Confirm events are live

1. Open **Events** in the dashboard and check that new moments appear after real product use (or a test signup).
2. Open **Growth** after you hire Ranla to see how those events feed segments and campaigns.

### 5. Wire more moments later

When you need a new product moment (for example “emit when the first meaningful action happens”):

- Ask the agent to wire that event, or
- Start **Wire** from **Events** (proposed row or empty state)

Ranla opens another scoped pull request for that moment. Status stays visible on **Events** (wiring → PR open → merged → live once the first matching event arrives).

---

## Path B — Install it yourself

Use this when you prefer to own the integration, or to add events the GitHub PR did not cover.

### 1. Create an account and API key

1. Sign up at [app.ranla.ai](https://app.ranla.ai).
2. Open **Home** (`/overview`) or **Settings → API keys** and click **Create API key**.
3. Copy the `rnl_…` secret once.

```bash
export RANLA_API_KEY=rnl_your_key_here
```

### 2. Install the SDK

```bash
npm install @supersend/ranla
```

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)
```

**Other languages** — same API, Ranla defaults (`https://api.ranla.ai`):

| Language | Install |
|----------|---------|
| Python | `pip install ranla` · `from ranla import Ranla` |
| Go | `go get github.com/Super-Send/supersendtx-sdks/go/ranla` |
| PHP | `composer require ranla/ranla` |
| Ruby | `gem install ranla` · `Ranla::Client` |

The legacy `supersendtx` packages on each registry remain supported for existing integrations.

Working in Cursor or Claude? You can also drive setup through the [MCP server](./ai/mcp.md) and [agent skill notes](./ai/agent-skill.md).

### 3. Track product events

Send events when something meaningful happens in your product. Ranla uses these for segments, automations, and the growth agent.

```ts
await client.events.trigger({
  name: 'user.created',
  user_id: 'user_123',
  email: 'ada@yourdomain.com',
  data: { plan: 'trial', source: 'signup' },
  idempotencyKey: 'evt_user_created_123',
})
```

Common first events:

| Event | When to fire |
|-------|----------------|
| `user.created` | Account or workspace created |
| `user.activated` | Finished onboarding or first value action |
| `subscription.started` | Paid or trial started |
| `subscription.churned` | Cancelled or expired |

REST equivalent:

```bash
curl -X POST https://api.ranla.ai/events \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_user_created_123" \
  -d '{
    "name": "user.created",
    "user_id": "user_123",
    "email": "ada@yourdomain.com",
    "data": { "plan": "trial" }
  }'
```

See [Events API](./api/events.md) for fields, idempotency, and automation matching.

### 4. Verify a sending domain

Lifecycle and transactional email must send from a domain you control.

1. **Domains → Add domain** in the dashboard.
2. Add DNS records (Cloudflare one-click if offered).
3. **Verify DNS** on the domain page.

Until DNS is verified, use sandbox self-test sends to your account email. See [Quickstart: send email](./quickstart.md) §4 for the full DNS table.

### 5. Send a test email (optional but recommended)

Confirm the pipe works before you rely on automations:

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@yourdomain.com",
    "to": "you@yourdomain.com",
    "subject": "Ranla pipe check",
    "html": "<p>Send path works.</p>"
  }'
```

Free tier: 3,000 emails/mo · 100/day · 1 domain. Add a payment method to unlock production sends to other recipients.

---

## Track your website

Product events tell you what people do *after* they sign up. The browser script tells you who showed up in the first place. It is a separate one-line install, and it is what fills **Acquisition → Analytics**.

### 1. Paste the script

1. Open **Home** in the dashboard and expand **Connect your marketing site**.
2. Copy the snippet for your account and paste it before `</body>` on every page you want counted.
3. Load a page on your own site — any page, no email link and no campaign click needed — then hit **Check again**. The badge turns **Installed** about two seconds after that pageview.

Two seconds is the whole wait: the beacon is acknowledged in milliseconds and a buffer writes it to the database every two seconds, so a page load and a click is the entire check. **Acquisition → Analytics** runs on the same beat — it reads today's traffic from those rows directly and only falls back to the five-minute rollup for history older than the last tick, so the first pageview is on the chart long before that tick lands.

The one thing that does lag: a report already open in a tab is cached for 60 seconds. Reload it rather than watching it.

Using Google Tag Manager? Connect your Google account from the same place, or paste the Custom HTML tag shown there — a plain `<script src>` tag pasted into Tag Manager loses its account key.

### 2. What it records

| Recorded | Detail |
|----------|--------|
| Pageviews | Including client-side route changes in single-page apps — no extra wiring for React, Next.js, Vue, or similar |
| Visits | A visit ends after 30 minutes of inactivity, or at UTC midnight |
| Source | Referrer plus `utm_source`, `utm_medium`, `utm_campaign`, `utm_term` and `utm_content`, classified into channels: search, social, AI assistants, email, referral, direct |
| Time on page | Engaged time only — a tab left open in the background does not inflate it |
| Outbound clicks and downloads | Automatic, for links to another site and links to files (PDF, ZIP, CSV, …) |
| Location and device | Country, region and city codes, plus browser, OS and device type |
| Revenue | Conversions recorded with `stx.convert()` or the [Conversions API](./api/conversions.md), tied to the visit that produced them |

No IP address is stored, there is no cross-site identifier and no fingerprint. Visitors are counted with a first-party cookie on your own domain. Known bots are dropped before anything is counted.

### 3. Custom events

Once the script has loaded, `stx.event()` records anything else worth marking on a page — it shows up on that visitor's journey in Analytics:

```js
stx.event('pricing_toggle', { plan: 'annual' })
```

Event names are capped at 64 characters, and up to 20 properties are kept per event (string values are trimmed at 256 characters). For money, use `stx.convert()` instead so the sale is counted as revenue:

```js
stx.convert({ goal: 'purchase', value_cents: 4900, currency: 'usd' })
```

`value_cents` is always integer cents: `4900` is $49.00.

### 4. Exclude traffic you do not want counted

These are attributes on the same script tag — no second snippet:

| Attribute | Effect |
|-----------|--------|
| `data-exclude="/admin/**,/preview/*"` | Comma-separated path patterns that are never recorded. `*` matches inside one path segment, `**` matches across segments. |
| `data-respect-dnt` | Honour the browser's Do Not Track signal. Off unless you add it, because some browsers send that header without the visitor ever asking for it. |
| `data-hostname="example.com"` | Report a fixed hostname instead of the one in the address bar — useful when one site is served on several domains or from preview URLs. |

```html
<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…"
        data-exclude="/admin/**" data-respect-dnt></script>
```

To stop **your own** visits from counting, run this once in your browser console on your site:

```js
localStorage.setItem('rnl_ignore', '1')
```

That is per browser, so each teammate does it on their own machine.

The same script also powers [on-site messages](./guides/on-site-messages.md) and `stx.identify()`, so installing it once covers all three.

---

## Turn on lifecycle (hire Ranla)

The growth workspace (agent, campaign cycles, autopilot) unlocks when you **hire Ranla** on a paid band. Until then, `/growth` shows an upsell — you can still connect GitHub, send events, and use the send API on the free tier.

In the dashboard after hire:

1. Open **Growth** and review what Ranla sees from your events.
2. Approve or edit a proposed campaign.
3. Optionally wire an [automation](./api/automations.md) for `user.created` → welcome sequence.

---

## Next steps

- [What is Ranla](./what-is-ranla.md)
- [Track your website](#track-your-website) · [On-site messages](./guides/on-site-messages.md)
- [Google Ads](./guides/google-ads.md) · [Revenue](./guides/revenue.md)
- [Connect analytics](./guides/connect-analytics.md) · [Events API](./api/events.md)
- [Automations](./api/automations.md) · [Templates](./api/templates.md)
- [Quickstart: send email](./quickstart.md)
- [Agent skill notes](./ai/agent-skill.md) · [MCP server](./ai/mcp.md)

---

<!-- canonical: https://docs.ranla.ai/quickstart -->

# Ranla — Quickstart

Send your first transactional email in about five minutes.

Migrating from another provider? Start with [Resend](./migration.md), [Postmark](./migration/postmark.md), [Amazon SES](./migration/ses.md), or [SendGrid](./migration/sendgrid.md), then mirror send + webhook flows from the hosted [API Explorer](https://docs.ranla.ai/api-explorer).

Building auth email? See [password reset](./guides/password-reset-emails.md), [Supabase Auth](./guides/supabase.md), and [Clerk / Auth.js](./guides/auth-provider-email.md).

Using React Email components? See [Send React Email](./guides/react-email.md).

**Hosted docs:** [docs.ranla.ai](https://docs.ranla.ai)  
**Dashboard:** [app.ranla.ai](https://app.ranla.ai)  
**API:** `https://api.ranla.ai`

---

## For AI agents

- **Index:** [docs.ranla.ai/llms.txt](https://docs.ranla.ai/llms.txt)
- **Full bundle:** [docs.ranla.ai/llms-full.txt](https://docs.ranla.ai/llms-full.txt)
- **OpenAPI:** [docs.ranla.ai/openapi.yaml](https://docs.ranla.ai/openapi.yaml)
- **Agent skill notes:** [docs.ranla.ai/ai/agent-skill](https://docs.ranla.ai/ai/agent-skill)
- **MCP server:** [docs.ranla.ai/ai/mcp](https://docs.ranla.ai/ai/mcp) (`ranla-mcp` on npm)
- **AI app builders:** [docs.ranla.ai/builders](https://docs.ranla.ai/builders) (Lovable, Replit, Bolt, Base44, v0 prompts)

Agents need an API key from **Settings → API keys** in the dashboard (step 3), or they can connect the hosted MCP server with OAuth instead.

---

## 1. Create an account

1. Open the dashboard at [app.ranla.ai](https://app.ranla.ai).
2. Sign up with email + password (or email code if you prefer).
3. If using email code: enter the code emailed to you.

---

## 2. Send a sandbox test (fastest path)

No domain or DNS required for the first sandbox send: create an API key (step 3), then send from the shared sandbox sender `noreply@mail.ranla.ai` to your account email — see **Sandbox self-test** in step 5.

### Use with Cursor or Claude

1. Create an API key in **Settings → API keys**, or skip the key and connect the hosted MCP server, which signs in with OAuth.
2. Add the `ranla-mcp` MCP server — see [MCP server](./ai/mcp.md).
3. Let the agent wire `POST /emails` (or the SDK) into your app and run the sandbox self-test.

See [`docs/ai/agent-skill.md`](./ai/agent-skill.md) and [`docs/ai/mcp.md`](./ai/mcp.md).

---

## 3. Create an API key

1. Open **Settings → API keys** in the dashboard and click **Create API key** (or use an existing `rnl_…` key). One key works for the whole workspace: the sending API, the CLI, and the MCP server.
2. Copy the secret — it is shown **once**.

```bash
export RANLA_API_KEY=rnl_your_key_here
```

---

## 4. Verify a sending domain (DNS setup — self-test from your domain on free)

Add and verify your domain on Sandbox to complete DNS setup. On the free plan you can **self-test from your verified domain to your account email** to confirm DNS and branding. **Free production** (send to other recipients) unlocks after a **verified domain and a payment method on file** — we do not charge until you upgrade. Caps: 3,000 emails/mo · 100/day · 1 domain. Upgrade to Pro or Scale for more volume.

### Dashboard (recommended)

1. Go to **Domains → Add domain** and enter your domain (e.g. `yourdomain.com`).
2. On the domain page (or in guided setup):
   - If your DNS is on Cloudflare: click **Sign in to Cloudflare** when offered — authorize once and we add the records.
   - Or **Settings → Integrations** → paste a Cloudflare API token (Zone DNS Edit) → Save, then **Apply DNS (Cloudflare)**.
   - If your DNS is at GoDaddy: switch to **GoDaddy**, paste an API key + secret for a one-time apply.
   - Otherwise paste the shown TXT records at your DNS host (merge SPF if you already have one).
3. Click **Verify DNS**.
4. Optional after verification: set **Delivery settings** on the domain detail page for:
   - open tracking
   - click tracking
   - `tls_mode` (`opportunistic` or `enforced`)
5. Check the built-in DMARC/BIMI guidance on the same page before you roll out branded inbox features.

| Type | Purpose |
|------|---------|
| TXT `_supersendtx.yourdomain.com` | Domain ownership |
| TXT `{selector}._domainkey.yourdomain.com` | DKIM (domain signing key) |
| CNAME `rp.yourdomain.com` | Return path → `rp.supersendtx.com` |
| TXT `yourdomain.com` | SPF (`include:spf.supersendtx.com`) |
| TXT `_dmarc.yourdomain.com` | DMARC |

Ownership, SPF, DKIM, and return-path are required to verify. Verify also confirms mail-server DKIM readiness so sends are signed with your domain (not the shared pool). Local Docker auto-verifies when `RANLA_DEV_AUTO_VERIFY=true`.
If a domain is already attached to another Ranla team, `POST /domains` returns a 409 with claim instructions instead of creating a duplicate owner.

### CLI (from your editor / terminal)

Save a Cloudflare token under **Settings → Integrations** first (recommended). Then:

```bash
export RANLA_API_KEY=rnl_your_key_here

npx -y --package=ranla-cli -- ranla domains add yourdomain.com

# Uses the Cloudflare token stored in Ranla (no local CLOUDFLARE_API_TOKEN needed)
npx -y --package=ranla-cli -- ranla domains apply yourdomain.com --provider cloudflare

npx -y --package=ranla-cli -- ranla domains verify yourdomain.com
```

Optional override: set `CLOUDFLARE_API_TOKEN` locally to apply with a machine token instead of the dashboard one. Vercel uses `VERCEL_API_TOKEN` and optional `VERCEL_TEAM_ID` the same way. GoDaddy can use stored dashboard credentials or local `GODADDY_API_KEY` / `GODADDY_API_SECRET`.

---

## 5. Send from your app

Pick one integration method below. Replace `you@yourdomain.com` with an address on your **verified** domain.

### Sandbox self-test (before DNS)

Use the shared sandbox sender on `mail.ranla.ai`, but only send to **your own account email**:

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@mail.ranla.ai",
    "to": "you@example.com",
    "subject": "Sandbox check",
    "html": "<p>Ranla sandbox works.</p>"
  }'
```

Once your domain is verified, you can self-test from your own domain to your account email:

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "you@example.com",
    "subject": "Verified domain check",
    "html": "<p>My domain works.</p>"
  }'
```

Add a payment method at **Settings → Billing** to unlock Free production (send to other recipients). Upgrade to Pro or Scale for more volume.

### curl (production)

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello from Ranla",
    "html": "<p>It works.</p>"
  }'
```

### Node.js SDK

```bash
npm install @supersend/ranla
```

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

const { id, status } = await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello from Ranla',
  html: '<p>It works.</p>',
})

console.log(id, status)
```

### CLI

```bash
RANLA_API_KEY=$RANLA_API_KEY npx -y --package=ranla-cli -- ranla emails send \
  --from you@yourdomain.com \
  --to user@example.com \
  --subject "Hello from Ranla" \
  --html "<p>It works.</p>"
```

Or install globally: `npm install -g ranla-cli`, then run `@supersend/ranla emails send …`.

---

## Success response

```json
{
  "id": "msg_abc123…",
  "status": "sent"
}
```

---

## Plan limits

When billing is enabled, Sandbox is for integration and self-test sends (hard daily and monthly caps). Until Free production is unlocked, sends are limited to your account email — from the shared sandbox sender or from a verified domain. Unlock Free production with a verified domain **and** a payment method on file (no charge until you upgrade). Paid Pool and Dedicated plans meter overage past included volume. Over Free/Sandbox limit:

```json
{ "error": { "message": "…", "code": "plan_limit", "upgrade_url": "/settings/billing" } }
```

HTTP **429**. Upgrade in the dashboard under **Settings → Billing**.

## Common errors

| HTTP | Meaning | Fix |
|------|---------|-----|
| 401 | Invalid or missing API key | Check `Authorization: Bearer rnl_…` |
| 403 | From domain not verified, sandbox/verified-domain recipient mismatch, or send to other recipients without Free production unlocked | Verify domain; self-test to your account email; add a payment method at Settings → Billing to unlock Free production |
| 400 | Missing `from`, `to`, or `subject` | Send required fields + `html` or `text` |
| 429 | Plan send limit (`code: plan_limit`) | Upgrade at Settings → Billing |
| 503 | Mail delivery temporarily unavailable | Retry later or contact support |

Full reference: [docs.ranla.ai/api-reference](https://docs.ranla.ai/api-reference)

---

## 6. Webhooks (optional)

1. Go to **Webhooks** in the dashboard (or use the API).
2. Add your HTTPS endpoint URL.
3. Copy the signing secret (`whsec_…`) — shown once.
4. Verify `SuperSendTX-Signature` on incoming `POST`s.

```ts
await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/supersendtx',
})
```

See [docs.ranla.ai/api-reference](https://docs.ranla.ai/api-reference) for payload shape and signature verification.

---

## 7. Receive email (optional)

Want an app inbox or agent mailbox?

1. Create a dedicated inbound subdomain such as `inbound.example.com`.
2. Add it with `inbound_enabled: true` (API) or `supersendtx domains add inbound.example.com --inbound true` (CLI).
3. Verify the domain, then publish the returned MX record.
4. Subscribe to `email.received` and/or poll `GET /received-emails`.

See [`docs/api/inbound.md`](./api/inbound.md) for the full flow and the MX conflict warning.

---

## 8. Event-driven automations (optional)

Ranla can trigger transactional sequences from custom events.

**Dashboard:** open **Automations**, create from a starter (or blank) on the visual canvas, configure steps in the side panel (send-email can use a published **Templates** entry or inline HTML), then Activate.

**CLI / API:** create and activate from a JSON file (handy in Cursor or CI):

```bash
supersendtx automations create --file ./welcome.json
supersendtx automations activate --id "$AUTOMATION_ID"
```

Then send the trigger event from your app:

```bash
curl -X POST https://api.ranla.ai/events \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_user_created_123" \
  -d '{
    "name": "user.created",
    "user_id": "user_123",
    "email": "user@example.com",
    "data": {
      "name": "Ada Lovelace"
    }
  }'
```

Response:

```json
{
  "event": {
    "id": "ae_123",
    "name": "user.created",
    "user_id": "user_123",
    "email": "user@example.com",
    "data": { "name": "Ada Lovelace" },
    "source": "api",
    "created_at": "2026-07-26T12:00:00.000Z"
  },
  "matched_automations": 1,
  "resumed_runs": 0,
  "cancelled_runs": 0
}
```

See [`docs/api/automations.md`](./api/automations.md) and [`docs/api/events.md`](./api/events.md).

---

## Next steps

- Docs home: [docs.ranla.ai](https://docs.ranla.ai)
- API reference: [docs.ranla.ai/api-reference](https://docs.ranla.ai/api-reference)
- Next.js quickstart: [docs.ranla.ai/frameworks/nextjs](https://docs.ranla.ai/frameworks/nextjs)
- React Email: [docs.ranla.ai/guides/react-email](https://docs.ranla.ai/guides/react-email)
- Node.js quickstart: [docs.ranla.ai/frameworks/node](https://docs.ranla.ai/frameworks/node)
- Send API: [`docs/api/emails.md`](./api/emails.md)
- Domains API: [`docs/api/domains.md`](./api/domains.md)
- Inbound email API: [`docs/api/inbound.md`](./api/inbound.md)
- Deliverability: [`docs/api/deliverability.md`](./api/deliverability.md)
- Events: [`docs/api/events.md`](./api/events.md)
- Templates: [`docs/api/templates.md`](./api/templates.md)
- Automations: [`docs/api/automations.md`](./api/automations.md)
- SMTP relay: [`docs/api/smtp.md`](./api/smtp.md)
- Webhooks: [`docs/api/webhooks.md`](./api/webhooks.md)
- AI onboarding: [docs.ranla.ai/llms.txt](https://docs.ranla.ai/llms.txt), [docs.ranla.ai/llms-full.txt](https://docs.ranla.ai/llms-full.txt), [`docs/ai/agent-skill.md`](./ai/agent-skill.md), [`docs/ai/mcp.md`](./ai/mcp.md) (`ranla-mcp` npm package)
- OpenAPI spec: [docs.ranla.ai/openapi.yaml](https://docs.ranla.ai/openapi.yaml)

---

<!-- canonical: https://docs.ranla.ai/authentication -->

# Authentication

Ranla authenticates API requests with Bearer API keys that start with `rnl_` or `stx_`. Newly created keys still start with `rnl_`. A `rnl_` key with the same secret after the prefix authenticates as the existing key.

## Obtain a key

1. Open the [dashboard](https://app.ranla.ai).
2. Go to **Settings → API keys** and click **Create API key**. One key works across the workspace: the sending API, the CLI, and the MCP server.
3. Copy the secret — it is shown **once**.

```bash
export RANLA_API_KEY=rnl_your_key_here
```

Keep keys server-side only. Never ship them in browser bundles or public repos.

## Request header

Send the key on every management and send request:

```bash
curl https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>It works.</p>"
  }'
```

### Node SDK

```javascript
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY)
```

### CLI

```bash
export RANLA_API_KEY=rnl_your_key_here
npx -y --package=ranla-cli -- ranla emails send \
  --from you@yourdomain.com \
  --to user@example.com \
  --subject "Hello" \
  --html "<p>It works.</p>"
```

## Base URLs

| Surface | URL |
|---------|-----|
| API | `https://api.ranla.ai` |
| Dashboard | `https://app.ranla.ai` |

## Unauthorized responses

Missing or invalid keys return **401** with:

```json
{
  "error": {
    "message": "Unauthorized"
  }
}
```

See [Errors](/errors) for the full error shape.

---

<!-- canonical: https://docs.ranla.ai/errors -->

# Errors

Ranla returns JSON errors that match the OpenAPI contract.

## Shape

```json
{
  "error": {
    "message": "Human-readable summary",
    "details": {}
  }
}
```

`details` is optional and may include field-level validation info.

## Common status codes

| Status | When |
|--------|------|
| `400` | Invalid JSON or failed validation |
| `401` | Missing/invalid `Authorization: Bearer rnl_…` |
| `403` | Authenticated but not allowed (e.g. unverified sending domain) |
| `404` | Resource not found |
| `409` | Conflict (e.g. domain already claimed) |
| `429` | Rate limited |
| `502` | Upstream mail delivery failure |

## Examples

### Unverified domain (403)

```json
{
  "error": {
    "message": "Sending domain is not verified"
  }
}
```

### Validation (400)

```json
{
  "error": {
    "message": "Validation failed",
    "details": {
      "to": "Required"
    }
  }
}
```

## Idempotency

Some write endpoints accept an `Idempotency-Key` header. Replays with the same key return the original success response instead of creating duplicates — see the [API Explorer](/api-explorer) and OpenAPI spec for which operations support it.

---

<!-- canonical: https://docs.ranla.ai/migration -->

# Migration from Resend

Also migrating from other providers?

- [Postmark](/migration/postmark)
- [Amazon SES](/migration/ses)
- [SendGrid](/migration/sendgrid)

---

If you are moving an existing Resend integration, the Ranla send flow maps closely:

- Bearer API keys
- `POST /emails` with a familiar JSON body
- Webhooks / activity for delivery outcomes

The main migration steps are:

1. swap the base URL
2. swap your API key to `rnl_...`
3. verify a sending domain in Ranla
4. update any provider-specific optional fields

---

## Quick mapping

| Resend | Ranla |
|--------|---------------|
| `https://api.resend.com` | `https://api.ranla.ai` |
| `re_...` API key | `rnl_...` API key |
| `POST /emails` | `POST /emails` |
| `from` must be verified | `from` must be verified |
| dashboard activity | dashboard activity + deliverability summary |

---

## Minimal curl diff

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>It works.</p>"
  }'
```

---

## Accepted payload aliases

Ranla accepts a few migration-friendly aliases on the HTTP send API:

- `htmlBody` or `html_body` -> `html`
- `textBody`, `text_body`, or `plain_body` -> `text`
- `replyTo` -> `reply_to`
- `scheduledAt` -> `scheduled_at`

Attachment aliases are also accepted:

- `filename` -> `name`
- `contentType` -> `content_type`
- `content` -> `data`
- `contentId` -> `content_id`

These aliases are meant to make low-friction migrations easier; new code should still prefer the canonical field names in docs/examples.

---

## Domain verification differences

Unlike provider-managed sandbox products, Ranla expects you to verify your own sending domain for production traffic.

Before DNS is ready, you can still self-test with the shared sandbox sender:

```json
{
  "from": "noreply@mail.ranla.ai",
  "to": "you@example.com",
  "subject": "Sandbox check",
  "html": "<p>Sandbox works.</p>"
}
```

Sandbox restriction:

- the sandbox `from` domain is only allowed when all recipients match the account email on the API key owner

Once your own domain is verified, switch `from` back to your branded domain.

---

## DNS apply

Ranla can write DNS for you in two ways:

- Cloudflare: save a token once under **Settings -> Integrations**
- GoDaddy: paste one-time API credentials on the domain detail page, or pass them through the SDK/CLI locally

See [`docs/api/domains.md`](./api/domains.md).

---

## SMTP

If your old integration still depends on SMTP, create credentials in the dashboard (**SMTP**) or via `POST /smtp-credentials`, then connect to `smtp.supersendtx.com:587` with username `supersendtx`. Same verified domains and plan limits as the HTTP API. Prefer `POST /emails` for new app code. Details: [`docs/api/smtp.md`](./api/smtp.md).

---

<!-- canonical: https://docs.ranla.ai/migration/postmark -->

# Migration from Postmark

Move transactional sends from Postmark to Ranla without changing your product’s email jobs — receipts, password resets, alerts, and invites still go out over `POST /emails`.

---

## Why teams switch

- **HTTP API + npm SDK** with a short path from API key to first send
- **Owned transactional mail infrastructure**, not a thin layer on rented cloud email
- **Sandbox → Pool → Dedicated** so you can test free, run production on a paid shared transactional network, then isolate on managed servers and IPs when you need allowlists

---

## Quick mapping

| Postmark | Ranla |
|----------|--------------|
| Server API token | `rnl_...` API key (`Authorization: Bearer`) |
| `https://api.postmarkapp.com` | `https://api.ranla.ai` |
| `POST /email` | `POST /emails` |
| Verified Sender Signature / domain | Verified sending domain in Ranla |
| Message Streams (Transactional) | Transactional-only product (no cold/marketing mix) |
| Webhooks | Webhooks + dashboard activity |

---

## Minimal send

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>It works.</p>"
  }'
```

Node:

```bash
npm install @supersend/ranla
```

```js
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY)
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>It works.</p>',
})
```

---

## Migration checklist

1. Create a Ranla account and API key
2. Add and verify your sending domain ([Domains](/domains))
3. Point your app’s send client at `https://api.ranla.ai` with `rnl_...`
4. Map Postmark fields: `From` → `from`, `To` → `to`, `Subject` → `subject`, `HtmlBody` → `html`, `TextBody` → `text`, `ReplyTo` → `reply_to`
5. Reconfigure webhooks to Ranla endpoints ([Webhooks](/webhooks))
6. Send a canary through Sandbox or your verified domain, then cut over

HTTP aliases accepted today: `htmlBody` / `html_body`, `textBody` / `text_body` / `plain_body`, `replyTo` → `reply_to`. Postmark’s PascalCase `HtmlBody` is **not** accepted — map it to `html` (or `htmlBody`) in your client. New code should use canonical names (`html`, `text`, `reply_to`).

---

## Domains and DNS

Production `from` addresses must use a domain verified in Ranla. Cloudflare and GoDaddy apply flows can write records for you — see [Domains](/domains).

Before DNS is ready, self-test with the shared sandbox sender on `mail.ranla.ai` (recipients limited to your account email). Details: [Quickstart](/quickstart).

---

## Related

- [Migration from Resend](/migration)
- [Migration from Amazon SES](/migration/ses)
- [Quickstart](/quickstart)

---

<!-- canonical: https://docs.ranla.ai/migration/ses -->

# Migration from Amazon SES

If you send transactional mail through Amazon SES (SDK, SMTP, or a thin API on top of SES), you can move the application-facing send path to Ranla while keeping the same jobs: auth mail, receipts, alerts, and notifications.

---

## What changes

| SES-oriented setup | Ranla |
|--------------------|--------------|
| AWS credentials / IAM | `rnl_...` API key |
| Regional SES endpoint | `https://api.ranla.ai` |
| `SendEmail` / `SendRawEmail` | `POST /emails` |
| SES-verified identity | Ranla verified domain |
| Configuration sets / event destinations | Webhooks + dashboard activity |
| Shared SES IP pools (typical) | Pool (owned transactional network) or Dedicated (managed servers + IPs) |

Ranla runs on **owned mail infrastructure**, not as a reseller of SES. That matters when you care who else shares the pipe — and when you later need Dedicated isolation.

---

## Minimal send

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>It works.</p>"
  }'
```

```js
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY)
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>It works.</p>',
})
```

---

## Migration checklist

1. Sign up at [app.ranla.ai](https://app.ranla.ai) and create an API key
2. Verify your sending domain ([Domains](/domains)) — SPF, DKIM, return path
3. Replace SES SDK calls with Ranla HTTP or the `supersendtx` npm package
4. Map bodies: HTML → `html`, text → `text`, reply addresses → `reply_to`
5. Point bounce/complaint/delivery handling at Ranla [webhooks](/webhooks)
6. Run parallel canary sends, then shift production traffic

---

## Sandbox vs production

- **Sandbox:** send from `noreply@mail.ranla.ai` to your account email only while integrating
- **Free production:** verified domain **and** a payment method on file (no charge until you upgrade) — 3,000 emails/mo · 100/day · 1 domain on the shared transactional network (Pool)
- **Pro (from $20/mo):** from 50,000 emails/mo · up to 10 domains · declining overage by tier
- **Scale:** higher volume tiers with declining overage (up to 1,000 domains)
- **Dedicated (from $299/mo):** managed server and IPs when you need isolation

See [Pricing](https://ranla.ai/pricing) and [Quickstart](/quickstart).

---

## SMTP

SES SMTP users can move to Ranla SMTP relay: host `smtp.supersendtx.com`, port `587` (STARTTLS), username `supersendtx`, password from a dashboard SMTP credential (`stxsmtp_…`). Same verified domains, plan limits, and suppressions as the HTTP API. Prefer `POST /emails` for new app code; use SMTP when the integration only exposes an SMTP form. Details: [SMTP](/smtp).

---

## Related

- [Migration from Resend](/migration)
- [Migration from Postmark](/migration/postmark)
- [Quickstart](/quickstart)

---

<!-- canonical: https://docs.ranla.ai/migration/sendgrid -->

# Migration from SendGrid

Move transactional sends from SendGrid to Ranla — receipts, password resets, alerts, and invites still go out over `POST /emails` with a simpler JSON body than SendGrid's v3 mail send payload.

---

## Why teams switch

- **Straightforward HTTP API** — one `POST /emails` instead of nested `personalizations` / `content` arrays
- **Owned transactional mail infrastructure**, separate from cold/outbound reputation
- **Sandbox → Pool → Dedicated** — test for free, run production on a shared transactional network, isolate on managed servers when you need allowlists

---

## Quick mapping

| SendGrid | Ranla |
|----------|--------------|
| `SG.` API key | `rnl_…` API key (`Authorization: Bearer`) |
| `https://api.sendgrid.com/v3/mail/send` | `https://api.ranla.ai/emails` |
| `personalizations[].to[]` | `to` (string or array) |
| `from.email` + `from.name` | `from` (single address string) |
| `content[]` with `type` / `value` | `html` and/or `text` |
| Dynamic templates (`template_id`) | Template `alias` on send |
| Event Webhook | Webhooks + dashboard activity |
| ASM / unsubscribe groups | Managed unsubscribe + suppressions |

---

## Minimal send

**SendGrid (v3):**

```bash
curl -X POST https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "user@example.com" }] }],
    "from": { "email": "you@yourdomain.com" },
    "subject": "Hello",
    "content": [{ "type": "text/html", "value": "<p>It works.</p>" }]
  }'
```

**Ranla:**

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello",
    "html": "<p>It works.</p>"
  }'
```

---

## Node.js

**SendGrid:**

```ts
import sgMail from '@sendgrid/mail'
sgMail.setApiKey(process.env.SENDGRID_API_KEY!)
await sgMail.send({
  to: 'user@example.com',
  from: 'you@yourdomain.com',
  subject: 'Hello',
  html: '<p>It works.</p>',
})
```

**Ranla:**

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>It works.</p>',
})
```

---

## Webhooks

SendGrid Event Webhook posts JSON arrays of events. Ranla sends one signed JSON object per delivery with `SuperSendTX-Signature` (HMAC-SHA256). Map event names as follows:

| SendGrid event | Ranla |
|----------------|--------------|
| `processed` | `email.sent` |
| `delivered` | `email.delivered` |
| `deferred` | `email.delivery_delayed` |
| `bounce` | `email.bounced` |
| `dropped` | `email.failed` or `email.suppressed` |
| `open` | `email.opened` |
| `click` | `email.clicked` |
| `spamreport` | `email.complained` |

Use **Send test event** on the dashboard webhooks page (or `POST /emails/test`) to verify your handler before cutover.

---

## Checklist

1. Create a Ranla API key (`rnl_…`)
2. Add and verify your sending domain (SPF, DKIM, return-path)
3. Swap the client to `api.ranla.ai` and map fields per table above
4. Recreate webhook endpoints and update signature verification
5. Send from Sandbox, then production after domain verify

---

## Compare

Product overview: [Transactional email on Ranla](https://ranla.ai/platform/transactional).

---

<!-- canonical: https://docs.ranla.ai/migration/from-rewardful -->

# Migration from Rewardful

Move an affiliate program from Rewardful to Ranla affiliates. Most of the move is a find-and-replace: links still use `?via=`, checkout still passes a referral id to Stripe, and commissions still come from your Stripe invoices.

---

## Quick mapping

| Rewardful | Ranla |
|-----------|--------------|
| API Secret (HTTP Basic auth, secret as username) | `rnl_…` full-access API key (`Authorization: Bearer`) |
| `https://api.getrewardful.com/v1` | `https://api.ranla.ai` |
| Affiliate | Partner — `/affiliates` |
| Campaign | Campaign — `/affiliate-campaigns` |
| Affiliate link / `token` | Link — `/affiliates/{id}/links`, `token` |
| Affiliate coupon | Per-partner promotion code |
| Referral (`conversion_state`: `visitor`, `lead`, `conversion`) | Referral — `/affiliate-referrals`, `status` `lead` → `active`. Anonymous visitors are counted as clicks, not referrals. |
| Commission (`state`: `pending`, `due`, `paid`, `voided`) | Commission — `/affiliate-commissions`, `status` `pending` → `earned` → `paid`, or `reversed` |
| Payout | Payout — `/affiliate-payouts` |
| Magic Link (SSO) | `POST /affiliates/{id}/login-link` |

## Browser script

| Rewardful | Ranla |
|-----------|--------------|
| Queue snippet + `<script async src="https://r.wdfl.co/rw.js" data-rewardful="…">` | `<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…">` — no queue snippet needed |
| `?via=` links | `?via=` links (also `?ref=`) — existing partner links keep working when you keep the tokens |
| `data-rewardful-params` (extra link params) | `data-ref-params` |
| `data-domains` (cross-domain tracking) | `data-ref-domains` |
| `?referral=<id>` (preload a referral) | `?referral=<id>` |
| `Rewardful.referral` | `stx.referral` (empty string when there is none) |
| `Rewardful.affiliate` (`false` when none) | `stx.affiliate` — `{ id, name, first_name }`, or `null` |
| `Rewardful.coupon` (the Stripe coupon object) | `stx.coupon` — `{ id, code, label }`, or `null` |
| `rewardful('ready', cb)` | `stx.ready(cb)` |
| `rewardful('convert', { email })` | `stx.referralSignup(email)` or `stx.identify({ email })` |
| `rewardful('source', token)` | `stx.referralSource(token)` |
| `<form data-rewardful>` (adds a hidden `referral` input) | Add the input yourself: `<input type="hidden" name="referral" data-stx-referral>` |

## Stripe

| Rewardful | Ranla |
|-----------|--------------|
| `client_reference_id: Rewardful.referral` on the Checkout Session | `client_reference_id: stx.referral` |
| `metadata.referral` on the customer | `metadata.ranla_referral` on the Checkout Session, customer, subscription or invoice |
| `metadata.rewardful = "false"` to skip a commission | `metadata.ranla = "false"` on the customer, subscription or invoice |
| Payment Links: a script you add appends `client_reference_id` | Automatic — the script adds `client_reference_id` to `buy.stripe.com` links |

## Campaign fields

| Rewardful | Ranla campaign |
|-----------|-----------------------|
| `reward_type: percent` / `amount` | `commission_type: percent` / `flat` |
| `commission_percent` (e.g. `30.0`) | `commission_bps` (e.g. `3000`) |
| `commission_amount_cents` | `commission_flat_cents` |
| `max_commission_period_months` | `recurring_months` (`null` = lifetime) with `commission_duration: recurring` |
| `max_commissions` = 1 | `commission_duration: once` |
| `days_before_referrals_expire` | `cookie_days` |
| `days_until_commissions_are_due` | `hold_days` |
| `minimum_payout_cents` | Program minimum payout (dashboard) |
| `private` | `visibility: private` |
| `default` | `is_default` (set with `make_default: true`) |

## Affiliate fields

| Rewardful | Ranla partner |
|-----------|----------------------|
| `first_name`, `last_name`, `email` | same |
| `state` (`active`, `disabled`, `suspicious`) | `status` (`active`, `pending`, `invited`, `suspended`, `rejected`) — `disabled` and `suspicious` map to `suspended` |
| `campaign.id` (`campaign_id` on create) | `campaign_id` (id or name) |
| `paypal_email` | `paypal_email` |
| `wise_email` | Partners add Wise or bank details in their portal |
| `links[].token` | `links[].token` |

## Webhook events

| Rewardful | Ranla |
|-----------|--------------|
| `affiliate.created` | `affiliate.created` |
| — (affiliates start `active`) | `affiliate.approved` — a partner became active |
| `affiliate.updated` | `affiliate.updated` |
| `referral.created` (a new visitor) | — (clicks are not sent as events) |
| `referral.lead` | `referral.created` |
| `referral.converted` | `referral.converted` |
| `commission.created` | `commission.created` |
| `commission.updated` (when it becomes due) | `commission.earned` |
| `commission.voided` | `commission.reversed` |
| `commission.paid` | `commission.paid` |
| `payout.created`, `payout.paid`, `payout.failed` | same names |

Rewardful's `affiliate.confirmed`, `affiliate_link.*`, `affiliate_coupon.*`, `sale.*`, `payout.due`, `payout.updated` and `*.deleted` events have no counterpart. Signatures use the `SuperSendTX-Signature` header — see [Webhooks](/webhooks#signature-verification).

---

## Import your partners

Export your affiliates from Rewardful, then import them in the dashboard (**Affiliates → Partners → Import CSV**) — upload the file or paste it. The columns are:

```csv
email,first_name,last_name,campaign,token,paypal_email
jane@example.com,Jane,Doe,Standard,jane,jane@example.com
```

- Only `email` is required. With a header row, columns can be in any order and extra columns are ignored; without one, the order above is assumed.
- `campaign` is a campaign name or id. Rows without one join the campaign you pick in the import dialog.
- `token` is the partner's existing link token, so their `?via=` links keep working. Tokens are 2–40 lowercase letters, digits and dashes: uppercase is lowercased and any other character becomes a dash. A token that is already taken gets a numbered variant (`jane2`), so check the partners list after the import.
- Imported partners start `active` and get no email unless you turn on the welcome email. Up to 5,000 rows per file; duplicate or invalid emails are skipped and listed.

To import from code instead, call `POST /affiliates` once per partner. Here a taken `token` returns `409` rather than a variant, so you know every link survived:

```bash
curl -X POST https://api.ranla.ai/affiliates \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","first_name":"Jane","token":"jane","campaign_id":"Standard","send_invite":false}'
```

See [Affiliates API → Create a partner](/affiliates#create-a-partner).

## Moving over

1. Turn on the program in the dashboard and create campaigns that match yours.
2. [Import your partners](#import-your-partners), keeping each one's `token`.
3. Swap the script tag and the Stripe metadata key, following the tables above. See the [affiliate tracking guide](/guides/affiliate-tracking).
4. Attribute existing customers to their partners from the dashboard so recurring commissions continue.
5. Pay the last Rewardful payout there, then let new commissions accrue here.

---

<!-- canonical: https://docs.ranla.ai/migration/from-tolt -->

# Migration from Tolt

Move an affiliate program from Tolt to Ranla affiliates. Links, checkout hand-off and commissions work much the same way; the names differ. One real difference: commissions come straight from your Stripe invoices, so there is no transactions call to make.

---

## Quick mapping

| Tolt | Ranla |
|------|--------------|
| API key (`Authorization: Bearer`) | `rnl_…` full-access API key (`Authorization: Bearer`) |
| `https://api.tolt.com/v1` | `https://api.ranla.ai` |
| Program | Your affiliate program (one per account) |
| Group / program commission settings | Campaign — `/affiliate-campaigns` |
| Partner | Partner — `/affiliates` |
| Link (`param` + `value`) | Link — `/affiliates/{id}/links`, `token` (the `value`) |
| Customer (`lead`, `trialing`, `active`, `canceled`) | Referral — `/affiliate-referrals` (`lead`, `trialing`, `active`, `cancelled`, …) |
| Transaction (`POST /v1/transactions`) | Not needed — the Stripe invoice behind a commission (`stripe_invoice_id`) |
| Commission (`pending`, `approved`, `rejected`) | Commission — `/affiliate-commissions` (`pending` → `earned` → `paid`, or `reversed`) |
| Payout | Payout — `/affiliate-payouts` |
| Promotion code | Per-partner promotion code |
| `POST /v1/clicks` + `POST /v1/customers` | `POST /affiliate-referrals` |

## Browser script

| Tolt | Ranla |
|------|--------------|
| `<script src="https://cdn.tolt.io/tolt.js" data-tolt="…">` | `<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…">` |
| Link param (`ref`, `via` or your own) | `?via=` and `?ref=` read by default; add others with `data-ref-params` |
| `window.tolt_referral` | `stx.referral` (empty string when there is none) |
| `window.tolt_data` (`partner_id`, `cookie_duration`, …) | `stx.affiliate` — `{ id, name, first_name }`, or `null` |
| `await window.tolt.signup(identifier)` (email or user id) | `stx.referralSignup(email)` or `stx.identify({ email })` — takes an email |

## Stripe

| Tolt | Ranla |
|------|--------------|
| `metadata.tolt_referral` on the Checkout Session or subscription | `metadata.ranla_referral` on the Checkout Session, customer, subscription or invoice |
| Payment Links: a script you add appends `client_reference_id=window.tolt_referral` | Automatic — the script adds `client_reference_id` to `buy.stripe.com` links |
| Buy Button / Pricing Table: `client-reference-id` set to `window.tolt_referral` | Same attribute, set to `stx.referral` inside `stx.ready` |
| — | `client_reference_id: stx.referral` on a Checkout Session you create |
| — | `metadata.ranla = "false"` excludes a customer, subscription or invoice |

## Partner fields

| Tolt `POST /v1/partners` | Ranla `POST /affiliates` |
|------|--------------|
| `first_name`, `last_name`, `email` | same (only `email` is required) |
| `program_id`, `group_id` | `campaign_id` (id or name) |
| `company_name`, `country_code` | `company`, `country` |
| `notify_partner` | `send_invite` |
| `payout_method: paypal` + `payout_details` | `paypal_email`; partners add Wise or bank details in their portal |
| Link created separately (`POST /v1/links`) | `token` — the primary link, created with the partner |

## Commission settings

| Tolt | Ranla campaign |
|------|-----------------------|
| Percentage / fixed commission | `commission_type: percent` (`commission_bps`, 3000 = 30%) / `flat` (`commission_flat_cents`) |
| One-time / recurring, duration in months | `commission_duration: once` / `recurring` with `recurring_months` (`null` = lifetime) |
| Cookie duration | `cookie_days` |
| Payout terms (NET-15 / 30 / 60) | `hold_days` (refund window before a commission is earned) plus the program's payout day |
| Tiered rates by customer count | `tiers: [{ min_paid_customers, commission_bps }]` |
| Minimum payout threshold | Program minimum payout (dashboard) |
| Auto payouts | Opt-in in the dashboard, with a cap — runs above it wait for your approval |

## Webhook events

| Tolt | Ranla |
|------|--------------|
| `partner.created` | `affiliate.created` |
| Partner approved | `affiliate.approved` |
| `referral.created` (a new customer) | `referral.created` |
| `referral.updated` (customer starts paying) | `referral.converted` |
| `commission.created` | `commission.created` |
| `commission.updated` (approved) | `commission.earned` |
| `commission.updated` (rejected, refunded) | `commission.reversed` |
| Commission paid | `commission.paid` |
| Payout events | `payout.created`, `payout.paid`, `payout.failed` |

Tolt lists its full set in the dashboard's Event Catalog; match any others there by meaning. Signatures use the `SuperSendTX-Signature` header — see [Webhooks](/webhooks#signature-verification).

---

## Import your partners

Export your partners from Tolt, then import them in the dashboard (**Affiliates → Partners → Import CSV**) — upload the file or paste it. The columns are:

```csv
email,first_name,last_name,campaign,token,paypal_email
jane@example.com,Jane,Doe,Standard,jane,jane@example.com
```

- Only `email` is required. With a header row, columns can be in any order and extra columns are ignored; without one, the order above is assumed.
- `campaign` is a campaign name or id. Rows without one join the campaign you pick in the import dialog.
- `token` is the `value` of the partner's Tolt link, so `?ref=jane` keeps working. Tokens are 2–40 lowercase letters, digits, dashes and underscores: uppercase is lowercased and any other character becomes a dash. A Tolt value like `michael_scott` imports unchanged, so `?ref=michael_scott` keeps working. A token that is already taken gets a numbered variant (`jane2`), so check the partners list after the import.
- Imported partners start `active` and get no email unless you turn on the welcome email. Up to 5,000 rows per file; duplicate or invalid emails are skipped and listed.

If your links use a param other than `via` or `ref`, list it on the script tag with `data-ref-params`.

To import from code instead, call `POST /affiliates` once per partner. Here a taken `token` returns `409` rather than a variant, so you know every link survived:

```bash
curl -X POST https://api.ranla.ai/affiliates \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","first_name":"Jane","token":"jane","send_invite":false}'
```

See [Affiliates API → Create a partner](/affiliates#create-a-partner).

## Moving over

1. Turn on the program in the dashboard and create campaigns that match your commission settings.
2. [Import your partners](#import-your-partners), keeping each one's link value as their `token`.
3. Replace server-side `POST /v1/clicks` and `POST /v1/customers` calls with `POST /affiliate-referrals` (`token` + `email`, optionally `stripe_customer_id`). Drop `POST /v1/transactions` calls — payments are read from your connected Stripe account.
4. Swap the script tag and the Stripe metadata key. See the [affiliate tracking guide](/guides/affiliate-tracking).
5. Attribute existing customers to their partners from the dashboard so recurring commissions continue.

---

<!-- canonical: https://docs.ranla.ai/guides/password-reset-emails -->

# Password reset email best practices

Password reset emails, email verification, and magic links are the highest-stakes transactional mail your product sends. A delayed or filtered message locks someone out of their own account. Send them with `POST /emails` (or the npm SDK) from a [verified domain](/domains).

This guide covers a production-ready **password reset email** flow: send examples, copy patterns, security habits, templates, and how to wire auth providers (Supabase, Clerk, Auth.js, Better Auth).

For the deeper product architecture (tokens, latency budgets, stream isolation), see [Transactional email on Ranla](https://ranla.ai/platform/transactional).

---

## Recommended flow

1. Create an API key in the dashboard
2. Verify your sending domain ([Domains](/domains)) — prefer a transactional subdomain such as `mail.yourdomain.com` or `tx.yourdomain.com`
3. When your app issues a reset or verify token, call Ranla with the link in `html` and `text`
4. Track delivery, bounce, and complaint events via [webhooks](/webhooks)

Treat provider acceptance (`200` + message `id`) as “queued,” not “in the inbox.” Wire webhooks if support needs a delivery timeline.

---

## Password reset email example

```js
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY)

export async function sendPasswordResetEmail({
  to,
  resetUrl,
  expiresInMinutes = 30,
}: {
  to: string
  resetUrl: string
  expiresInMinutes?: number
}) {
  return client.emails.send({
    from: 'noreply@mail.yourdomain.com',
    to,
    subject: 'Reset your password',
    html: `
<p>We received a request to reset your password.</p>
<p><a href="${resetUrl}">Reset password</a></p>
<p>This link expires in ${expiresInMinutes} minutes. If you did not request a reset, you can ignore this email.</p>
`.trim(),
    text: `We received a request to reset your password.\n\nReset password: ${resetUrl}\n\nThis link expires in ${expiresInMinutes} minutes. If you did not request a reset, you can ignore this email.`,
  })
}
```

curl:

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@mail.yourdomain.com",
    "to": "user@example.com",
    "subject": "Reset your password",
    "html": "<p>We received a request to reset your password.</p><p><a href=\"https://yourapp.com/reset?token=…\">Reset password</a></p><p>This link expires in 30 minutes. If you did not request a reset, you can ignore this email.</p>",
    "text": "We received a request to reset your password.\n\nReset password: https://yourapp.com/reset?token=…\n\nThis link expires in 30 minutes. If you did not request a reset, you can ignore this email."
  }'
```

### Copy habits that help inbox placement

- Use a specific subject (`Reset your password`) — avoid vague “Action required”
- Include a plain-text part every time
- Put the reset URL in both the button/link and as visible text for clients that strip HTML
- State expiry clearly
- Never attach marketing modules or unsubscribe footers to auth mail

---

## Email verification example

```js
await client.emails.send({
  from: 'noreply@mail.yourdomain.com',
  to: user.email,
  subject: 'Verify your email',
  html: `<p>Confirm your email address:</p><p><a href="${verifyUrl}">Verify email</a></p><p>If you did not create an account, you can ignore this email.</p>`,
  text: `Confirm your email address: ${verifyUrl}\n\nIf you did not create an account, you can ignore this email.`,
})
```

---

## Magic link and OTP examples

Magic links are the same send pattern with a shorter-lived URL:

```js
await client.emails.send({
  from: 'noreply@mail.yourdomain.com',
  to,
  subject: 'Your sign-in link',
  html: `<p><a href="${magicUrl}">Sign in</a></p><p>This link expires in 10 minutes.</p>`,
  text: `Sign in: ${magicUrl}\n\nThis link expires in 10 minutes.`,
})
```

One-time codes should stay short and readable in plain text (users often read OTP mail on a second device):

```js
await client.emails.send({
  from: 'noreply@mail.yourdomain.com',
  to,
  subject: 'Your verification code',
  html: `<p>Your code is <strong>${otp}</strong>.</p><p>It expires in 10 minutes.</p>`,
  text: `Your code is ${otp}.\n\nIt expires in 10 minutes.`,
})
```

---

## Security habits (application side)

Ranla delivers the message; your app owns the token.

- Generate high-entropy, single-use tokens and store them hashed
- Keep expiry short (minutes for magic links / OTP; tens of minutes for password reset)
- Return the same response whether or not the account exists (no enumeration)
- Prefer first-party HTTPS links — avoid third-party URL shorteners in auth mail
- Make sends idempotent so retries do not create three reset emails

---

## Latency and deliverability

Auth mail should target **seconds** from user action to inbox. Budget queue time in your workers, not only the HTTP round trip to the API.

- Authenticate the sending domain with SPF, DKIM, and DMARC before production traffic ([Domains](/domains))
- Keep auth mail on a transactional identity — do not send campaigns from the same subdomain
- Suppress hard bounces immediately so retries do not burn reputation ([Suppressions](/suppressions))

If resets land in spam, diagnose authentication and reputation before rewriting subject lines — see [Deliverability](/deliverability).

---

## Templates

For repeated auth copy, store HTML in [Templates](/templates) and send by alias with variables (`reset_url`, `expires_in`) instead of inlining markup in every service. Keep a plain-text body on the send call or in the template so filters and accessibility stay covered.

---

## Auth providers (Supabase, Clerk, Auth.js, Better Auth)

Those products often expect **custom SMTP** or an **email hook**. Ranla supports both:

| Provider | Typical path | Guide |
|----------|--------------|-------|
| Supabase | Auth hook → `POST /emails`, or custom SMTP | [Supabase Auth email](/guides/supabase) |
| Clerk | `email.created` webhook → `supersendtx-clerk` | [Clerk email](/guides/clerk) |
| Auth.js / NextAuth | `supersendtx-authjs` email provider | [Auth.js email](/guides/authjs) |
| Better Auth | `sendResetPassword` / `sendVerificationEmail` | [Better Auth email](/guides/better-auth) |

Overview of the shared pattern: [Auth provider email](/guides/auth-provider-email). SMTP relay details: [SMTP](/smtp).

---

## Related

- [Auth provider email](/guides/auth-provider-email)
- [Emails API](/emails)
- [Webhooks](/webhooks)
- [Templates](/templates)
- [React Email](/guides/react-email)
- [Quickstart](/quickstart)
- [Transactional email on Ranla](https://ranla.ai/platform/transactional)

---

<!-- canonical: https://docs.ranla.ai/guides/auth-provider-email -->

# Auth provider email (password reset, magic links, verification)

Many auth stacks let you bring your own email for **password reset**, magic links, verification, and OTP messages. Ranla is built for that traffic over the **HTTP API**, with [SMTP relay](/smtp) when a provider only accepts custom SMTP.

> Prefer HTTP hooks or server routes calling `POST /emails` when the provider supports them. Use SMTP credentials from the dashboard when the product only exposes an SMTP form.

For standalone send examples and copy patterns, see [Password reset email best practices](/guides/password-reset-emails).

---

## Pattern (all providers)

1. Verify `yourdomain.com` (or a sending subdomain like `mail.yourdomain.com`) in Ranla
2. Create an `rnl_...` API key
3. In the auth provider’s **email hook**, **custom mailer**, or your app’s auth callback, send with Ranla
4. Keep `from` on your verified domain
5. Optionally subscribe to [webhooks](/webhooks) for delivery, bounce, and complaint events

```js
import { Ranla } from '@supersend/ranla'

const tx = new Ranla(process.env.RANLA_API_KEY)

export async function sendAuthEmail({
  to,
  subject,
  html,
  text,
}: {
  to: string
  subject: string
  html: string
  text?: string
}) {
  return tx.emails.send({
    from: 'noreply@mail.yourdomain.com',
    to,
    subject,
    html,
    text,
  })
}
```

Use this helper from password-reset, verification, and magic-link paths so every auth message shares one authenticated identity.

---

## Supabase

Use the **Send Email** auth hook with an Edge Function that calls `POST /emails`, **or** configure [Supabase custom SMTP](/smtp) with a Ranla SMTP credential (host `smtp.supersendtx.com`, username `supersendtx`). Full hook setup: **[Supabase Auth email](/guides/supabase)**.

For local testing before your domain verifies, use the Ranla sandbox sender limited to your account email ([Quickstart](/quickstart)).

---

## Clerk

Clerk has no custom SMTP form for auth templates. Turn off **Delivered by Clerk**, listen for `email.created`, and deliver with [`supersendtx-clerk`](https://github.com/Super-Send/supersendtx-clerk):

```ts
import { verifyWebhook } from '@clerk/nextjs/webhooks'
import { createClerkEmailDeliverer } from 'supersendtx-clerk'

const deliver = createClerkEmailDeliverer({
  from: 'noreply@mail.yourdomain.com',
})

export async function POST(req: Request) {
  const evt = await verifyWebhook(req)
  if (evt.type === 'email.created') {
    await deliver(evt.data)
  }
  return new Response('ok')
}
```

Full walkthrough: **[Clerk email](/guides/clerk)**.

---

## Auth.js (NextAuth)

Use the drop-in **Ranla** email provider for magic links and verification flows:

```ts
import NextAuth from 'next-auth'
import SuperSendTX from 'supersendtx-authjs'

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: /* database adapter required */,
  providers: [
    SuperSendTX({ from: 'noreply@mail.yourdomain.com' }),
  ],
})
```

Set `AUTH_SUPERSENDTX_KEY` or `RANLA_API_KEY`. Full walkthrough: **[Auth.js / NextAuth email](/guides/authjs)**.

---

## Better Auth

Better Auth uses `sendVerificationEmail` / `sendResetPassword` callbacks — wire those to `POST /emails` (or the npm SDK) with the same `from` domain as your other transactional mail. Full walkthrough: **[Better Auth email](/guides/better-auth)**.

---

## Checklist

- [ ] Domain verified in Ranla (SPF / DKIM / return-path)
- [ ] `from` matches that domain (prefer a transactional subdomain)
- [ ] Password reset, verification, and magic-link paths all use the same sender identity
- [ ] Secrets only in server env (`RANLA_API_KEY`)
- [ ] HTML **and** plain-text bodies on auth sends
- [ ] Webhooks optional but recommended for delivery/bounce visibility
- [ ] Sandbox used only for self-tests before production cutover

---

## Related

- [Password reset email best practices](/guides/password-reset-emails)
- [Clerk email](/guides/clerk)
- [Auth.js / NextAuth email](/guides/authjs)
- [Better Auth email](/guides/better-auth)
- [Supabase Auth email](/guides/supabase)
- [Emails API](/emails)
- [SMTP](/smtp)
- [Migration guides](/migration)
- [Transactional email on Ranla](https://ranla.ai/platform/transactional)

---

<!-- canonical: https://docs.ranla.ai/guides/supabase -->

# Supabase Auth email with Ranla

Send Supabase signup, magic link, password reset, and invite emails through Ranla using the **Send Email** auth hook and an Edge Function.

> Ranla does **not** require the Send Email hook if your provider supports custom SMTP. Create an SMTP credential in the dashboard and paste host, username `supersendtx`, and password into Supabase → Authentication → SMTP. See [SMTP relay](/smtp).

For hook-based delivery (Edge Functions), use the HTTP API (`POST /emails`) from your handler — the same pattern Supabase documents for other ESPs.

---

## When to use this

- You built on **Supabase Auth** (often via Lovable, Vite, or Next.js) and want branded mail on your domain
- You outgrew Supabase’s built-in SMTP limits or need delivery visibility in Ranla
- You want one transactional provider for auth mail **and** product mail (receipts, alerts)

---

## Architecture

1. User triggers auth (signup, reset, magic link, etc.)
2. Supabase Auth calls your **Send Email** hook (HTTPS Edge Function)
3. The function verifies the webhook signature, builds the message, and calls `POST https://api.ranla.ai/emails`
4. Return `200` with `{}` so Supabase knows the email was handled

Reference: [Supabase Send Email Hook](https://supabase.com/docs/guides/auth/auth-hooks/send-email-hook).

---

## Prerequisites

1. Ranla account + `rnl_…` API key
2. Verified sending domain (or Sandbox for self-tests only — see [Quickstart](/quickstart))
3. Supabase project with the [Supabase CLI](https://supabase.com/docs/guides/cli) installed

---

## 1. Create the Edge Function

```bash
supabase functions new send-email
```

`supabase/functions/send-email/index.ts`:

```ts
import { Webhook } from 'https://esm.sh/standardwebhooks@1.0.0'

const hookSecret = (Deno.env.get('SEND_EMAIL_HOOK_SECRET') ?? '').replace(/^v1,whsec_/, '')
const apiKey = Deno.env.get('RANLA_API_KEY')
const fromEmail = Deno.env.get('SUPERSENDTX_FROM_EMAIL') ?? 'noreply@yourdomain.com'
const projectRef = Deno.env.get('SUPABASE_PROJECT_REF')

const subjects: Record<string, string> = {
  signup: 'Confirm your email',
  recovery: 'Reset your password',
  invite: 'You have been invited',
  magiclink: 'Your sign-in link',
  email_change: 'Confirm your new email',
  email_change_new: 'Confirm your new email',
  reauthentication: 'Your verification code',
}

function confirmationUrl(emailData: {
  token_hash: string
  email_action_type: string
  redirect_to: string
}) {
  const base = `https://${projectRef}.supabase.co/auth/v1/verify`
  const params = new URLSearchParams({
    token: emailData.token_hash,
    type: emailData.email_action_type,
    redirect_to: emailData.redirect_to,
  })
  return `${base}?${params.toString()}`
}

Deno.serve(async (req) => {
  if (req.method !== 'POST') {
    return new Response('method not allowed', { status: 405 })
  }
  if (!apiKey || !hookSecret || !projectRef) {
    return new Response('server misconfigured', { status: 500 })
  }

  const payload = await req.text()
  const headers = Object.fromEntries(req.headers)

  try {
    const wh = new Webhook(hookSecret)
    const { user, email_data } = wh.verify(payload, headers) as {
      user: { email: string }
      email_data: {
        token: string
        token_hash: string
        redirect_to: string
        email_action_type: string
      }
    }

    const action = email_data.email_action_type
    const subject = subjects[action] ?? 'Notification'
    const link = confirmationUrl(email_data)

    const html =
      action === 'reauthentication'
        ? `<p>Your verification code is <strong>${email_data.token}</strong></p>`
        : `<p><a href="${link}">${subject}</a></p>`

    const text =
      action === 'reauthentication'
        ? `Your verification code is ${email_data.token}`
        : `${subject}: ${link}`

    const res = await fetch('https://api.ranla.ai/emails', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        from: fromEmail,
        to: user.email,
        subject,
        html,
        text,
      }),
    })

    if (!res.ok) {
      const body = await res.text()
      throw new Error(`Ranla ${res.status}: ${body}`)
    }
  } catch (error) {
    console.error(error)
    return new Response(JSON.stringify({ error: String(error) }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    })
  }

  return new Response(JSON.stringify({}), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  })
})
```

Customize subjects and HTML (or render [React Email](/guides/react-email) in the function) for production.

---

## 2. Set secrets and deploy

`supabase/functions/.env` (local) — do not commit:

```bash
RANLA_API_KEY=rnl_your_key_here
SUPERSENDTX_FROM_EMAIL=noreply@yourdomain.com
SUPABASE_PROJECT_REF=your-project-ref
SEND_EMAIL_HOOK_SECRET=v1,whsec_...   # from Supabase dashboard after step 3
```

```bash
supabase secrets set --env-file supabase/functions/.env
supabase functions deploy send-email --no-verify-jwt
```

Note the deployed function URL (e.g. `https://<project-ref>.supabase.co/functions/v1/send-email`).

---

## 3. Enable the Send Email hook

**Alternative:** If you prefer Supabase’s built-in SMTP settings UI, create an SMTP credential in Ranla (**SMTP** in the dashboard) and configure [custom SMTP in Supabase](https://supabase.com/docs/guides/auth/auth-smtp) with host `smtp.supersendtx.com`, port `587`, username `supersendtx`, and your credential password. Skip the hook steps below.

In [Supabase Dashboard → Authentication → Hooks](https://supabase.com/dashboard/project/_/auth/hooks):

1. Add **Send Email** hook
2. Type: **HTTPS**
3. URL: your Edge Function URL
4. **Generate secret** — copy the `v1,whsec_…` value into `SEND_EMAIL_HOOK_SECRET`
5. Save

Redeploy or update secrets if you generated the secret after the first deploy.

While the hook is enabled, Supabase does **not** send auth mail itself — your function must succeed and return `200` + `{}`.

---

## 4. Auth email types

Handle every `email_action_type` your app uses:

| `email_action_type` | Typical use |
|---------------------|-------------|
| `signup` | Email confirmation |
| `recovery` | Password reset |
| `magiclink` | Passwordless sign-in |
| `invite` | User invite |
| `email_change` | Confirm email change |
| `email_change_new` | Confirm new address (secure email change) |
| `reauthentication` | Step-up OTP |

If the hook is on and a type is missing from your templates, that mail can fail silently.

---

## 5. Sandbox vs production

| Stage | `from` | `to` |
|-------|--------|------|
| Sandbox (no domain verified) | `noreply@mail.ranla.ai` (or your sandbox domain) | Your Ranla account email only |
| Verified domain (no payment method) | `noreply@yourdomain.com` | Account email only |
| Free production / paid | `noreply@yourdomain.com` | Any recipient |

Verify your domain in Ranla, then add a payment method to unlock Free production before switching `SUPERSENDTX_FROM_EMAIL` to real users.

---

## 6. Webhooks (optional)

Subscribe to `email.delivered`, `email.bounced`, and `email.complained` in Ranla to monitor auth mail health. See [Webhooks](/webhooks).

---

## Lovable / AI builders

If you generated the app in Lovable, store `RANLA_API_KEY` in project secrets and ask the agent to wire this hook — see [Lovable + Ranla](/builders/lovable).

---

## Related

- [Auth provider email (Clerk, Auth.js)](/guides/auth-provider-email)
- [Password reset emails](/guides/password-reset-emails)
- [React Email](/guides/react-email)

---

<!-- canonical: https://docs.ranla.ai/guides/better-auth -->

# Better Auth email with Ranla

Better Auth has a large [plugin catalog](https://better-auth.com/docs/plugins) (Magic Link, Email OTP, Organization, Stripe, etc.).

What it does **not** have is a third-party “email provider” plugin. Email delivery is always **your callback**:

| Surface | Callback you supply |
|---------|---------------------|
| Core email verification | `emailVerification.sendVerificationEmail` |
| Core password reset | `emailAndPassword.sendResetPassword` |
| [Magic Link plugin](https://www.better-auth.com/docs/plugins/magic-link) | `magicLink({ sendMagicLink })` |
| [Email OTP plugin](https://better-auth.com/docs/plugins/email-otp) | `emailOTP({ sendVerificationOTP })` |
| Organization invites | `organization({ sendInvitationEmail })` |

Ranla’s integration is `createBetterAuthEmail` from [`supersendtx-better-auth`](https://github.com/Super-Send/supersendtx-better-auth): one helper that returns those callbacks, wired to `POST /emails`.

Better Auth’s own hosted mail (`@better-auth/infra`) is a separate product. This guide is for bringing **your** Ranla account.

---

## Prerequisites

1. Ranla account + `rnl_…` API key
2. Verified sending domain (or Sandbox for self-tests — see [Quickstart](/quickstart))
3. Better Auth app

```bash
npm install supersendtx-better-auth @supersend/ranla better-auth
```

```bash
RANLA_API_KEY=rnl_your_key_here
```

Public package: [`supersendtx-better-auth`](https://github.com/Super-Send/supersendtx-better-auth) (also available as `supersendtx/better-auth` from the core SDK).

---

## Full setup (core + plugins)

```ts
// lib/auth.ts
import { betterAuth } from 'better-auth'
import { magicLink, emailOTP, organization } from 'better-auth/plugins'
import { createBetterAuthEmail } from 'supersendtx-better-auth'

const email = createBetterAuthEmail({
  from: 'noreply@yourdomain.com',
  apiKey: process.env.RANLA_API_KEY!,
  appUrl: process.env.BETTER_AUTH_URL, // used for invite links
})

export const auth = betterAuth({
  emailVerification: {
    sendVerificationEmail: email.sendVerificationEmail,
  },
  emailAndPassword: {
    enabled: true,
    sendResetPassword: email.sendResetPassword,
  },
  plugins: [
    magicLink({
      sendMagicLink: email.sendMagicLink,
    }),
    emailOTP({
      sendVerificationOTP: email.sendVerificationOTP,
    }),
    organization({
      sendInvitationEmail: email.sendInvitationEmail,
    }),
  ],
})
```

Only enable the plugins you use. Core callbacks work without any plugins.

---

## What each callback sends

| Helper | Tag | Content |
|--------|-----|---------|
| `sendVerificationEmail` | `auth=verify` | Verification link |
| `sendResetPassword` | `auth=reset` | Reset link |
| `sendMagicLink` | `auth=magic-link` | Sign-in link |
| `sendVerificationOTP` | `auth=otp-{type}` | One-time code (`sign-in`, `email-verification`, `forget-password`) |
| `sendInvitationEmail` | `auth=invite` | Org invite link (`{appUrl}/accept-invitation/{id}`) |

Customize templates with `email.sendAuthEmail({ to, subject, html, text, tag })` or `email.sendLinkEmail(...)`.

---

## Options

| Option | Default | Purpose |
|--------|---------|---------|
| `from` | required | Verified sender |
| `apiKey` | `process.env.RANLA_API_KEY` | API key |
| `baseUrl` | `https://api.ranla.ai` | API base URL |
| `appUrl` | — | Base URL for organization invite links |
| `fireAndForget` | `true` | Don’t await send in the auth request (Better Auth timing guidance). Set `false` in tests. |
| `client` | — | Inject a `SuperSendTX` instance |

---

## Related

- [Better Auth plugins](https://better-auth.com/docs/plugins)
- [Auth provider email](/guides/auth-provider-email)
- [Node.js SDK](/frameworks/node)
- [Password reset emails](/guides/password-reset-emails)

---

<!-- canonical: https://docs.ranla.ai/guides/authjs -->

# Auth.js / NextAuth email with Ranla

[Auth.js](https://authjs.dev) (NextAuth) magic-link sign-in needs an **email provider** and a **database adapter** (tokens are stored in the DB).

Ranla ships a drop-in provider: `SuperSendTX` from [`supersendtx-authjs`](https://github.com/Super-Send/supersendtx-authjs) (also `supersendtx/authjs`).

---

## Prerequisites

1. Ranla account + `rnl_…` API key
2. Verified sending domain (or Sandbox for self-tests — see [Quickstart](/quickstart))
3. Auth.js app with a [database adapter](https://authjs.dev/getting-started/database)

```bash
npm install supersendtx-authjs @supersend/ranla next-auth
```

```bash
AUTH_SUPERSENDTX_KEY=rnl_your_key_here
# or: RANLA_API_KEY=rnl_your_key_here
```

---

## Setup

```ts
// auth.ts
import NextAuth from 'next-auth'
import SuperSendTX from 'supersendtx-authjs'
// import your adapter, e.g. Prisma / Drizzle / …

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: /* … */,
  providers: [
    SuperSendTX({
      from: 'noreply@yourdomain.com',
    }),
  ],
})
```

Users sign in at `/api/auth/signin` with email. Ranla delivers the magic link (`auth=authjs-magic-link` tag).

---

## Options

| Option | Default | Purpose |
|--------|---------|---------|
| `from` | sandbox-style placeholder | Verified sender (set this for production) |
| `apiKey` | `AUTH_SUPERSENDTX_KEY` or `RANLA_API_KEY` | API key |
| `baseUrl` | `https://api.ranla.ai` | API base URL |
| `maxAge` | `86400` (24h) | Token lifetime (seconds) |
| `sendVerificationRequest` | built-in | Custom email body / send logic |
| `client` | — | Inject a `SuperSendTX` instance (tests) |

---

## Customize the email

Pass your own `sendVerificationRequest` (Auth.js pattern):

```ts
SuperSendTX({
  from: 'noreply@yourdomain.com',
  async sendVerificationRequest({ identifier, url, provider }) {
    const { SuperSendTX: Client } = await import('@supersend/ranla')
    const tx = new Client(process.env.RANLA_API_KEY!)
    await tx.emails.send({
      from: provider.from,
      to: identifier,
      subject: 'Your sign-in link',
      html: `<p><a href="${url}">Sign in</a></p>`,
      text: `Sign in: ${url}`,
    })
  },
})
```

Or send with [React Email](/guides/react-email) from that callback.

---

## Related

- [Auth.js email authentication](https://authjs.dev/getting-started/authentication/email)
- [Auth provider email](/guides/auth-provider-email)
- [Better Auth email](/guides/better-auth)
- [Node.js SDK](/frameworks/node)

---

<!-- canonical: https://docs.ranla.ai/guides/clerk -->

# Clerk email with Ranla

[Clerk](https://clerk.com) has no custom SMTP form for auth mail. To send verification codes, magic links, and similar templates through Ranla:

1. Turn off **Delivered by Clerk** on the templates you want to own
2. Subscribe to the `email.created` webhook
3. Deliver with [`supersendtx-clerk`](https://github.com/Super-Send/supersendtx-clerk) (also `supersendtx/clerk`)

---

## Prerequisites

1. Ranla account + `rnl_…` API key
2. Verified sending domain (or Sandbox for self-tests — see [Quickstart](/quickstart))
3. Clerk app with webhook signing secret

```bash
npm install supersendtx-clerk @supersend/ranla @clerk/nextjs
```

```bash
RANLA_API_KEY=rnl_your_key_here
SUPERSENDTX_FROM_EMAIL=noreply@yourdomain.com
```

---

## Webhook route

```ts
// app/api/webhooks/clerk/route.ts
import { verifyWebhook } from '@clerk/nextjs/webhooks'
import { createClerkEmailDeliverer } from 'supersendtx-clerk'

const deliver = createClerkEmailDeliverer({
  from: process.env.SUPERSENDTX_FROM_EMAIL!,
  // apiKey: process.env.RANLA_API_KEY,
})

export async function POST(req: Request) {
  const evt = await verifyWebhook(req)
  if (evt.type === 'email.created') {
    await deliver(evt.data)
  }
  return new Response('ok')
}
```

When `delivered_by_clerk` is still `true`, the helper returns `null` and does not send (avoids double delivery). Turn delivery off in the Clerk dashboard for each template you want Ranla to own.

Point the Clerk webhook endpoint at this route and subscribe to **email.created**.

---

## Options

| Option | Default | Purpose |
|--------|---------|---------|
| `from` | — (required) | Verified sender |
| `apiKey` | `RANLA_API_KEY` | API key |
| `baseUrl` | `https://api.ranla.ai` | API base URL |
| `skipIfDeliveredByClerk` | `true` | Skip when Clerk still delivers |
| `force` | `false` | Send even when `delivered_by_clerk` is true |
| `client` | — | Inject a `SuperSendTX` instance (tests) |

Sends are tagged `auth=clerk-<slug>` (or `clerk-email`) and use idempotency key `clerk-email-<id>` when Clerk provides an email id.

---

## SMTP alternative

If you only need SMTP fields somewhere else in your stack, create a Ranla [SMTP](/smtp) credential (`smtp.supersendtx.com`). Clerk auth templates themselves still go through the webhook path above.

---

## Related

- [Auth provider email](/guides/auth-provider-email)
- [Auth.js / NextAuth email](/guides/authjs)
- [Better Auth email](/guides/better-auth)
- [Node.js SDK](/frameworks/node)

---

<!-- canonical: https://docs.ranla.ai/guides/payload -->

# Payload CMS email with Ranla

[Payload](https://payloadcms.com) apps need transactional email for auth and notifications. Ranla ships a Payload 3 email adapter: `supersendtxAdapter` from [`supersendtx-payload`](https://github.com/Super-Send/supersendtx-payload) (also `supersendtx/payload`).

---

## Install

```bash
npm install supersendtx-payload @supersend/ranla
```

```bash
RANLA_API_KEY=rnl_your_key_here
```

---

## Payload email adapter

```ts
// payload.config.ts
import { buildConfig } from 'payload'
import { supersendtxAdapter } from 'supersendtx-payload'

export default buildConfig({
  email: supersendtxAdapter({
    defaultFromAddress: 'noreply@yourdomain.com',
    defaultFromName: 'Acme',
    // apiKey: process.env.RANLA_API_KEY,
  }),
  // collections, …
})
```

Payload then routes auth mail and `payload.sendEmail()` through Ranla (`product=payload` tag).

### Options

| Option | Purpose |
|--------|---------|
| `defaultFromAddress` | Verified From address (required) |
| `defaultFromName` | Display name (required) |
| `apiKey` | Falls back to `RANLA_API_KEY` |
| `baseUrl` | Override API base (tests / self-hosted) |
| `overrideRecipientAddress` | Force all mail to one address (local/dev) |
| `client` | Inject a `SuperSendTX` instance (tests) |

---

## Nodemailer transport (optional)

If you prefer Nodemailer + `@payloadcms/email-nodemailer`:

```bash
npm install supersendtx-nodemailer @supersend/ranla nodemailer
```

```ts
import nodemailer from 'nodemailer'
import { createSuperSendTXTransport } from 'supersendtx-nodemailer'

export const transport = nodemailer.createTransport(
  createSuperSendTXTransport({
    apiKey: process.env.RANLA_API_KEY!,
  }),
)
```

Wire that transport into Payload’s Nodemailer email adapter for your Payload major version. Prefer the first-party `supersendtxAdapter` when you can.

---

## Direct SDK

```ts
import { Ranla } from '@supersend/ranla'

const tx = new Ranla(process.env.RANLA_API_KEY!)

await tx.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Welcome.</p>',
})
```

---

## Related

- [Node.js + Nodemailer](/frameworks/node)
- [Better Auth](/guides/better-auth) (if Payload auth uses Better Auth)
- [Next.js](/frameworks/nextjs)

---

<!-- canonical: https://docs.ranla.ai/guides/n8n -->

# n8n community node

Send **Ranla** transactional email from [n8n](https://n8n.io) workflows with the community package [`n8n-nodes-supersendtx`](https://github.com/Super-Send/n8n-nodes-supersendtx).

This integrates **Ranla** only (`rnl_` API keys, `api.ranla.ai`). It is not the SuperSend cold-email product.

## Install

In n8n: **Settings → Community Nodes → Install** → `n8n-nodes-supersendtx`.

Self-hosted alternative:

```bash
npm install n8n-nodes-supersendtx
```

## Credentials

1. Create an API key in the Ranla dashboard (`rnl_…`).
2. In n8n, add **Ranla API** credentials with that key.
3. Leave **API Base URL** as `https://api.ranla.ai` unless you use a custom deployment.

## Send an email

1. Add the **Ranla** node.
2. Resource: **Email** → Operation: **Send**.
3. Set **From** (verified domain), **To**, **Subject**, and **HTML** and/or **Text**.
4. Optional: Reply-To, CC/BCC, idempotency key, schedule, template id, unsubscribe.

The node maps to `POST /emails`. See [Send emails](/api/emails).

## Other operations

| Operation | Use |
|-----------|-----|
| Get | Fetch one email by id |
| Get Many | List recent sends (limit + cursor) |

## Verification status

The package follows n8n’s [community node standards](https://docs.n8n.io/integrations/community-nodes/build-community-nodes/) (no runtime dependencies, MIT, declarative HTTP). After npm publish with provenance, submit it in the [n8n Creator Portal](https://creators.n8n.io/nodes) for in-app discovery.

---

<!-- canonical: https://docs.ranla.ai/guides/react-email -->

# Send React Email with Ranla

Use [React Email](https://react.email) to author components, preview them locally, then **send React Email** through the Ranla Node SDK — without tying delivery to a single ESP. The SDK accepts a `react` element and compiles it to HTML before `POST /emails`.

You do **not** need to fork React Email or add `@react-email/components` to Ranla — keep authoring in your app. Ranla is **not affiliated** with the React Email project; we are a transactional send API that optionally renders your components at send time.

## About React Email

[React Email](https://react.email) is a **separate open-source project** (MIT license) for authoring email UIs with React. Install `@react-email/render` and optional `@react-email/components` in **your** application. Ranla does not bundle React Email — the SDK optionally calls `@react-email/render` at send time to produce HTML for our API. Author and preview with React Email’s own CLI; delivery is through Ranla.

---

## Prerequisites

- A Ranla API key (`rnl_…`)
- A verified sending domain (or sandbox: `from` = `noreply@mail.ranla.ai`, `to` = your account email)
- Node 18+

---

## 1. Install

```bash
npm install @supersend/ranla @react-email/render react
# Optional — components + local preview tooling from React Email
npm install @react-email/components
npx create-email@latest
```

`@react-email/render` is an **optional peer** of `supersendtx`. Install it only if you use the `react` option. Without it, send with `html` / `text` / `template` as usual.

---

## 2. Author and preview

Create a component (example):

```tsx
// emails/WelcomeEmail.tsx
import * as React from 'react'
import { Html, Button, Text } from '@react-email/components'

export function WelcomeEmail({ name }: { name: string }) {
  return (
    <Html>
      <Text>Hi {name}, welcome aboard.</Text>
      <Button href="https://yourapp.com/dashboard">Open dashboard</Button>
    </Html>
  )
}

export default WelcomeEmail
```

Preview with React Email’s CLI / app (`npx email dev` or your project’s create-email setup). Ranla is not involved until you send.

---

## 3. Send with the SDK

```ts
import { Ranla } from '@supersend/ranla'
import { WelcomeEmail } from './emails/WelcomeEmail'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.emails.send({
  from: 'onboarding@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  react: WelcomeEmail({ name: 'Ada' }),
})
```

The SDK calls `@react-email/render` and POSTs `{ from, to, subject, html }` to `https://api.ranla.ai/emails`.

**Rules:**

- `react` is mutually exclusive with `html`, `text`, and `template`
- Server-side only — never put `rnl_` in the browser
- Same auth, sandbox, and domain rules as any other send ([Quickstart](/quickstart), [Agent skill notes](/ai/agent-skill))

---

## 4. Next.js (Route Handler)

```ts
// app/api/send-welcome/route.ts
import { NextResponse } from 'next/server'
import { Ranla } from '@supersend/ranla'
import { WelcomeEmail } from '@/emails/WelcomeEmail'

const tx = new Ranla(process.env.RANLA_API_KEY!)

export async function POST(request: Request) {
  const { to, name } = (await request.json()) as { to: string; name: string }

  const result = await tx.emails.send({
    from: 'onboarding@yourdomain.com',
    to,
    subject: 'Welcome',
    react: WelcomeEmail({ name }),
  })

  return NextResponse.json(result)
}
```

More Next.js patterns: [Next.js framework guide](/frameworks/nextjs).

---

## 5. Keep templates in your repo

Rendering at send time means your app must redeploy to change copy. If you want your
components to stay in git but let the send happen by alias — so a teammate can trigger
sends, and non-engineers can read what went out — push the rendered output to a template:

```bash
supersendtx templates push ./emails/WelcomeEmail.tsx \
  --alias welcome \
  --subject "Welcome" \
  --props '{"name":"Ada"}' \
  --publish
```

The CLI imports the file **in your process**, renders it with `@react-email/render`, and
uploads the resulting HTML and text. Your component source never leaves your machine.

- `--alias` is the key. The command creates the template on first push and updates it after.
- `--subject` is required only when creating.
- `--props` supplies props for rendering. Use `{{variable}}` placeholders in the output for
  values that should be substituted per send.
- `--publish` cuts a new published version, which is what `template: { id: 'welcome' }` sends.
- `.html` and `.txt` files work too; `--text ./welcome.txt` attaches a hand-written text part.

TypeScript and JSX files need a loader. Install `tsx` (`npm install -D tsx`) or pre-render to
`.html`.

Then send by alias from anywhere, with no component import:

```ts
await client.emails.send({
  from: 'onboarding@yourdomain.com',
  to: 'user@example.com',
  template: { id: 'welcome', variables: { name: 'Ada' } },
})
```

Wire the push into CI to keep the platform in sync with `main`.

---

## 6. Already have HTML?

If you render elsewhere (or export from React Email yourself), send `html` instead of `react`:

```ts
await client.emails.send({
  from: 'onboarding@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Hi Ada</p>',
})
```

Or use a published [dashboard template](/templates) with `template: { id | alias, variables }`.

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Error about `@react-email/render` | `npm install @react-email/render react` |
| `403` unverified domain | Verify DNS or use sandbox `from` / account `to` |
| Want MCP / agents | [MCP server](/ai/mcp) · [Agent Skills](/ai/agent-skills) — agents should link React Email’s own skills for authoring |

---

## FAQ

### Can I use React Email without Resend?

Yes. React Email is an open-source authoring toolchain. Ranla’s Node SDK accepts `react` the same way many teams expect from a modern send API: install `supersendtx` + `@react-email/render`, pass your component to `emails.send({ react })`, and we deliver HTML over our transactional infrastructure. Preview still uses React Email’s CLI.

### Is `react` the same as dashboard templates?

No. `react` renders in **your** Node process at send time (or you push rendered HTML with `supersendtx templates push`). Dashboard templates are stored aliases with variables for non-engineers and multi-language SDKs. Many teams use React Email in git for critical flows and aliases for stable receipts.

### Why did send fail with a peer dependency error?

The `react` option requires `@react-email/render` (and `react`) installed in the app. Without that peer, use `html`, `text`, or `template` instead — or run `npm install @react-email/render react`.

---

## Related

- [Templates API](/templates) — server-side aliases and variables
- [Password reset emails](/guides/password-reset-emails)
- [Transactional email on Ranla](https://ranla.ai/platform/transactional)
- [Node.js](/frameworks/node) · [Next.js](/frameworks/nextjs)
- React Email docs: [react.email](https://react.email)

---

<!-- canonical: https://docs.ranla.ai/guides/connect-analytics -->

# Connect PostHog, Amplitude, or Mixpanel

Use the analytics you already run so Ranla can segment, automate, and send on product moments — without opening a GitHub pull request for every event.

**Prefer wiring events in your app?** See [Instrument your product](/instrument-quickstart). You can use both paths: GitHub for missing first-party events, analytics for moments you already track.

---

## What you get

1. **Read** — Ranla can list which events your project already fires and inspect one person.
2. **Actable moments** — You pick which events matter. Ranla copies those events for people who have an email into its own ledger.
3. **History + live** — About the last 30 days of allowlisted history lands quietly (ingest only). New events can trigger automations after you mark them actable.

Ranla does **not** run vendor query languages as segments, and it does not treat every event in the project as actable until you choose.

---

## Prerequisites

1. A Ranla account on [app.ranla.ai](https://app.ranla.ai)
2. A read-only (or appropriate) API key / credentials from PostHog, Amplitude, or Mixpanel
3. Events that include an email or that can be tied to a contact Ranla already knows

---

## Connect in the dashboard

1. Open **Settings → Integrations**.
2. Choose **PostHog**, **Amplitude**, or **Mixpanel**.
3. Paste the credentials Ranla asks for (for PostHog, a personal or project API key with read access is typical).
4. Save. Ranla can now read your project’s event taxonomy.

You can connect more than one analytics tool; mark moments actable per source.

---

## Mark moments actable

1. Review the events Ranla discovered (or ask the agent which moments matter for activation, trial, or paid).
2. Allowlist the events you want copied into Ranla’s ledger.
3. Confirm people have email on those events (or that contacts already exist).

Until a moment is actable, Ranla may read it for inspection but will not copy it for sends or automations.

---

## Use the moments

Once actable events land:

- Build **segments** and **audiences** on those event names and properties
- Trigger **automations** on new occurrences
- Ask the **agent** to draft campaigns against the same ledger

Transactional mail (`POST /emails`) and lifecycle flows share suppressions — a marketing unsubscribe does not block password resets.

---

## API and Events ledger

Copied analytics events join the same product-event surface as [Events](/events). You can still `POST /events` from your app when you want first-party emission.

---

## Related

- [Instrument your product](/instrument-quickstart) — GitHub / SDK path
- [Events](/events) — REST contract for product events
- [What is Ranla](/what-is-ranla) — product overview
- [Changelog](https://ranla.ai/changelog) — recent ships

---

<!-- canonical: https://docs.ranla.ai/guides/on-site-messages -->

# On-site messages

Show banners or modals to anonymous visitors on your marketing site with Ranla’s tracking snippet. Collect an email on the message itself, or send people to a link—and when someone identifies in your product, Ranla can stitch the visit to a contact.

---

## What you get

- **Anonymous reach** — Message people before they have an email in Ranla
- **Page rules** — Show on selected paths (for example pricing or blog)
- **Path-aware offers** — Separate messages per path (pricing vs blog vs docs) with different copy and After submit URLs
- **When to show** — Immediately, exit intent, after scroll %, or after a delay
- **Email capture or link** — Collect email on the banner/modal, or open a URL
- **After submit URL** — Optional link after a successful capture (thank-you page, PDF, booking link)
- **Automation hook** — Capture fires `on_site.email_captured` so an automation can send the asset by email
- **Acquisition report** — See which paths create contacts (Growth → On-site → Acquisition)
- **Identify stitch** — Call `stx.identify()` after signup in your app so later email can continue the conversation

On-site messages are not a replacement for email automations. They are the on-site channel next to lifecycle and transactional mail.

---

## Prerequisites

1. A Ranla account on [app.ranla.ai](https://app.ranla.ai)
2. The marketing-site tracking snippet installed (`/t.js` for your account)
3. Permission to edit **Growth → On-site** in the dashboard

---

## Install the snippet

1. Open **Home** (workspace setup) or **Conversions → Install** / tracking setup in the app.
2. Copy the Ranla tracking snippet for your account.
3. Paste it on the marketing site you want to message (every page where messages should appear).

The snippet loads the tracker and evaluates active on-site messages for the current URL.

---

## Create a message

1. Open **Growth → On-site**.
2. Create a message (banner or modal).
3. Set copy, theme, and **where it appears** (page path prefix).
4. Choose **when to show**: immediately, exit intent, after scroll %, or after a delay.
5. Choose the call to action:
   - **Link** — button label + URL (visitor clicks and goes there)
   - **Collect email** — email field + submit label; optional **After submit** URL
6. Publish when ready.

Draft messages do not show to visitors. Visitors who already identified do not see messages.

When someone submits an email on a **Collect email** message, Ranla creates or updates the contact, links the anonymous visitor, counts the message as **Identified**, removes the banner, and fires the product event `on_site.email_captured`.

### Path-aware offers

Create **separate messages** for different paths instead of one generic banner:

| Path | Example offer |
|------|----------------|
| `/pricing` | Collect email → After submit = demo booking |
| `/blog` | Collect email → After submit = checklist PDF |
| `/docs` | Link or capture → trial signup |

Use a path prefix rule on each message so the right offer shows on the right page.

---

## After submit + deliver by email

**After submit** is a normal web link. If set, the browser goes there after a valid email submit. If empty, the message dismisses and the visitor stays on the page.

To **email** the asset (recommended for magnets):

1. Open **Automations** and create a flow triggered by `on_site.email_captured` (or use the **On-site lead magnet** template).
2. Send the PDF / checklist / next step from that automation.
3. Optionally still set After submit for an instant thank-you page.

Event properties include `path`, `message_id`, and `visitor_key` when available.

---

## Acquisition report

Open **Growth → On-site → Acquisition** to see:

- Which **paths** created contacts in the last 90 days
- Which **messages** converted the most Identified visitors

---

## Identify visitors

Even with on-message capture, call identify when someone signs up or logs in in your product so Ranla can attach prior anonymous activity to the contact:

```js
stx.identify({ email: 'user@example.com' })
```

Exact helper names follow the snippet your account installs. Identify after you know the email.

---

## Related

- [Instrument your product](/instrument-quickstart) — product events in the app
- [Connect analytics](/guides/connect-analytics) — PostHog / Amplitude / Mixpanel
- [Inbound](/inbound) — reply to email from the dashboard
- [Changelog](https://ranla.ai/changelog) — recent ships

---

<!-- canonical: https://docs.ranla.ai/guides/google-ads -->

# Google Ads

Connect your Google Ads account so Ranla can see spend, credit conversions, and propose changes on **Grow → Paid**. Budget and live ads only change after you approve.

---

## What you get

- **Spend and hierarchy** — campaigns, ad groups, ads, keywords, and search terms on Grow → Paid
- **Verified conversions** — Ranla sends conversions it can prove back to Google when that path is on
- **Audiences** — sync eligible segments for Customer Match when you accept the terms
- **Proposals, not silent spends** — Ranla can draft campaigns or edits; you approve before money moves

Paid is the operate desk. Whether acquisition is worth it shows on [Revenue](/guides/revenue).

---

## Connect

1. Open **Settings → Integrations → Google Ads**.
2. Sign in with Google and pick the ad account Ranla should use.
3. Save. Open **Grow → Paid** to confirm spend and structure show up.

You do not need a Google Cloud project or developer token. Connect and choose the account.

---

## Tracking so paid clicks stick

Install the [tracking snippet](/instrument-quickstart#track-your-website) on your marketing site. After signup in your product, call:

```js
stx.identify({ email: user.email })
```

That stitches the ad click to the contact. Without it, Paid LTV on Revenue stays incomplete even when Ads and Stripe look fine. Details: [Revenue](/guides/revenue).

---

## Approvals

Anything that changes budget, bids, or live creatives goes through Ranla’s approval card. Reject or edit before it applies. Read-only browsing on Paid never needs approval.

---

## Next steps

- [Revenue](/guides/revenue) — produced wins and paid payback
- [Modes](/guides/modes) — Draft, Propose, Autopilot
- [Instrument your product](/instrument-quickstart) — snippet + identify
- [Connect analytics](/guides/connect-analytics) — product moments for email

---

<!-- canonical: https://docs.ranla.ai/guides/revenue -->

# Revenue

**Grow → Revenue** shows which channel last-touched a conversion, then whether paid acquisition is paying back.

Email, Paid, and Other are last-touch credit from the same conversion ledger. Dollars appear when the conversion has an amount; otherwise you see the count. Payback, Paid LTV, and CAC stay on the page as supporting ads math.

It is not a Stripe Dashboard clone, and it is not a multi-touch attribution explorer.

---

## What you see

- **Email / Paid / Other** for the selected date range (default 30 days)
- Supporting **payback, Paid LTV, CAC, ARPU** when those pipes exist
- A **Trend** chart of verified CAC vs current LTV — same date range controls as Acquisition → Analytics
- A channel table (Paid CAC; Email conversions when they exist)
- Named gaps when Stripe, Ads, or identify is missing — those do not hide Email wins

Paid LTV only counts Stripe customers who have an ad-click first touch on their contact. Company-wide LTV is the wider Stripe book.

---

## What to connect

| Need | Where |
|------|--------|
| Stripe | Settings → Integrations → Stripe |
| Google Ads spend | Settings → Integrations → Google Ads, then Grow → Paid |
| Ad click → customer | Tracking snippet + `stx.identify({ email })` after signup |

Connect order does not matter. The scoreboard fills as each piece lands.

---

## Identify after signup

```js
stx.identify({ email: user.email })
```

Call this when the user is signed in (signup and ideally login). It links the anonymous visit — and any Google click id on it — to the contact. Names and plan belong on `POST /contacts`; identify only needs email for this stitch.

If Revenue says identify is missing, wire that call (or ask Ranla to open a PR when GitHub is connected).

---

## Paid vs Revenue

| Page | Job |
|------|-----|
| **Grow → Paid** | Run the ad account — spend, drafts, approvals |
| **Grow → Revenue** | What email and ads last-touched, and whether paid acquisition pays back |

---

## Next steps

- [Google Ads](/guides/google-ads) — connect and operate Paid
- [Instrument your product](/instrument-quickstart) — snippet + events
- [On-site messages](/guides/on-site-messages) — capture before signup

---

<!-- canonical: https://docs.ranla.ai/guides/seo -->

# Search

Connect Search Console so Ranla can see what you already earn from search. The SEO desk ranks the pages worth building. Ranla writes the draft, you edit it in place, and you publish it on your site. Nothing publishes on its own.

When someone asks an AI what to use, that is the same job: show up. Answer-engine work uses the same list, not a second product.

---

## What you get

- **Queries and movers** on the SEO desk, from Search Console
- **A ranked Actions list** of pages worth writing, priced in revenue rather than clicks
- **A full page draft** you can edit in place, then copy as markdown or download for your CMS
- **Competitors** as a source for the questions they already rank, not a public compare page on this site

No traffic history yet is fine. Ranla starts from the questions your product can honestly serve.

---

## Connect

1. Open **Settings → Integrations → Search Console**.
2. Sign in with Google and pick the property Ranla should read.
3. Save. Open the **SEO** desk to confirm queries and pages show up.

---

## Approvals

Ranla never publishes a page for you. Read the draft, edit it or ask Ranla for changes in the thread, then publish it yourself. Approve marks the page done so Ranla can propose the next one.

---

## Next steps

- [Modes](/guides/modes): Draft, Propose, Autopilot
- [Brand](/guides/brand): voice and product facts every page reads
- [Instrument your product](/instrument-quickstart): track the conversions a page should earn

---

<!-- canonical: https://docs.ranla.ai/guides/reddit -->

# Social

Grow → Reddit finds threads where buyers already ask, drafts a reply, and keeps score. Finding and drafting are free. Posting needs a connected Reddit account you approve.

---

## What you get

- **Find**: phrases your customers type and scored threads. New conversations and older threads that rank on Google or get cited by AI answers are separate lists, and each thread shows when it was posted
- **Draft**: a reply with safety checks. You edit before anything posts
- **Post**: from a connected account after you approve, or copy and post yourself
- **Rankings**: threads search and answer engines already cite
- **Leads**: people who asked for what you sell, with a message ready to send
- **Follow-up**: a posted reply is checked on day 1, 3, and 7 to make sure it stayed up

When no account is connected, the desk is still a task list. Approved replies wait until you connect or paste them yourself.

---

## Connect

1. Open **Grow → Reddit**.
2. Connect a Reddit account you are willing to post from.
3. Approve each reply (in the app or Slack) before it posts.

Ranla will not post from an account you did not connect, and it will not post without your yes.

---

## Approvals

Every post waits on you. Drafts can start before the account is connected. Live posting does not.

---

## Next steps

- [Modes](/guides/modes): Draft, Propose, Autopilot
- [Brand](/guides/brand): voice the drafts read
- [Search](/guides/seo): the same “show up where buyers look” job on your own site

---

<!-- canonical: https://docs.ranla.ai/guides/creative -->

# Creative

Grow → Creative is the studio for campaign and ad images. Compose uses Brand Style (colours, type, logo). Renders land in the library. Attach them to a campaign or an ad when you are ready.

---

## What you get

- **Library** of assets you already have
- **Stock search** for a background
- **Compose**: preview first, then render into the library
- **Brand lock**: headlines and logo come from Brand Style, not from a freeform drawing

Creative does not own how you look or talk. That lives on [Brand](/guides/brand). Compose reads Style. Other jobs still ask before they send, spend, publish, post, or merge.

---

## Use it

1. Open **Grow → Brand** and confirm Style has a logo, palette, and type. Seed from your website if it is empty.
2. Open **Grow → Creative**.
3. Compose an image. Preview. Create when it looks right.
4. The render finishes in the background and appears in the library.

You can start from stock, an upload, or a generated background. On-image type and the logo are stamped from Brand, not invented in the picture.

---

## Approvals

Compose saves an asset. It does not publish an ad or send an email. Paid and campaigns still wait on your yes.

---

## Next steps

- [Brand](/guides/brand): Style, Voice, Product
- [Google Ads](/guides/google-ads): attach images when you run Paid
- [Modes](/guides/modes): Draft, Propose, Autopilot

---

<!-- canonical: https://docs.ranla.ai/guides/brand -->

# Brand

Grow → Brand is the look, talk, and product facts every draft reads. Seed it from your website. You edit it. Brand saves. It does not publish, send, spend, post, or merge.

---

## What you get

| Tab | Job |
|------|-----|
| **Style** | Logo, palette, type. Creative stamps this onto images. |
| **Voice** | How drafts should sound. |
| **Profile** | One-liner, who it is for, who it is not for. |
| **Product** | What you actually sell. |
| **Competitors** | Who you compete with, so drafts stay honest. The public site still does not name them. |
| **Sources** | Website seed plus optional GitHub product context. |

Email, ads, pages, and Creative use the same kit so the work sounds like one company.

---

## Seed from the website

1. Open **Grow → Brand**.
2. Paste your website URL on Sources, or use Build Brand from site.
3. Edit Style, Voice, Profile, Product, and Competitors until they read true.

GitHub is optional extra context. The website URL is enough to start.

---

## Approvals

Brand is not a publish step. Saving the kit does not send mail, spend ads, merge a PR, or post on social. The jobs that use Brand still ask.

---

## Next steps

- [Creative](/guides/creative): images from Style
- [Search](/guides/seo): pages that read Product and Voice
- [Modes](/guides/modes): Draft, Propose, Autopilot

---

<!-- canonical: https://docs.ranla.ai/guides/events -->

# Events

Grow → Events is the live inventory of product moments, plus in-flight wiring as a pull request you merge. The other jobs cannot run without this.

The API resource page at [Product events](/events) is how you emit events yourself. This how-to is the dashboard desk.

---

## What you see

- **Live**: events already arriving, with volume and recent activity
- **In flight**: instrumentation Ranla has proposed or already opened a pull request for

A long wiring list no longer buries what is actually firing.

---

## What to connect

| Need | Where |
|------|--------|
| First-party events | GitHub so Ranla can open a PR, or the SDK / REST yourself |
| Analytics copy | Settings → Integrations → PostHog, Amplitude, or Mixpanel, then mark moments actable |
| Tracking on the site | [Instrument your product](/instrument-quickstart) |

Connect order does not matter. Live fills as events arrive.

---

## In flight is a pull request

1. Open **Grow → Events**.
2. Read Live for what already fires.
3. In flight shows recommended events and open PRs.
4. Review and merge. Ranla does not push to your default branch.

---

## Next steps

- [Instrument your product](/instrument-quickstart): snippet, GitHub, SDK
- [Connect analytics](/guides/connect-analytics): copy moments you already track
- [Product events](/events): REST resource
- [Modes](/guides/modes): Draft, Propose, Autopilot

---

<!-- canonical: https://docs.ranla.ai/guides/modes -->

# Modes

Draft, Propose, and Autopilot are how you tell Ranla how far it may go. Caps and the 5,000-person rule still apply in every mode. Set them on **Settings → Ranla**.

Start free. On the free plan Ranla reads your product, builds audiences, and drafts and proposes work so you can judge it first. Paying is what lets it schedule, send, and keep going on its own.

---

## The three modes

| Mode | What it does |
|------|----------------|
| **Draft** | Nothing sends, spends, publishes, posts, or lands in your repo until you do it. |
| **Propose** | It asks before each email, ad, page, post, or pull request, in the app or Slack. |
| **Autopilot** | It runs inside the limits you set. Big or expensive work still waits. |

Any audience over 5,000 people needs your approval in every mode. Ranla can tighten its own limits. It never loosens them.

---

## Caps that always hold

You set the frequency cap, the daily account cap, and the audience size above which a send waits. They are enforced in the send path, not asked for in a prompt, so they hold on every send.

Defaults are two emails per person per week at least 48 hours apart. Sends stop mid-flight if complaints pass 0.1% or bounces pass 5%.

---

## Slack

When Ranla parks something for you, it can post the card to Slack with Approve, Adjust, and Open. Decide there and the work carries on. Resolve it in the app and the Slack card closes itself. Slack does not skip the mode you set.

---

## Free vs paid

| Free | Paid |
|------|------|
| Draft and propose the six jobs | Schedule, send, spend, publish, post, and run on its own inside your caps |
| Connect GitHub, analytics, Search Console, Ads, Reddit | Same connections. Paying does not remove approvals for large or expensive work |

CTA on the site is **Start free**. There is no book-a-demo motion.

---

## Next steps

- [Search](/guides/seo): page drafts you publish
- [Google Ads](/guides/google-ads): approve before spend
- [Social](/guides/reddit): approve before a post
- [Events](/guides/events): merge before wiring ships

---

<!-- canonical: https://docs.ranla.ai/guides/affiliate-tracking -->

# Affiliate tracking

How a partner's click becomes a referral, and how that referral follows the person into Stripe so the partner is paid for every invoice.

You need three things in place:

1. The affiliate program turned on in the dashboard (**Affiliates**), with Stripe connected.
2. The browser script on your marketing site and your app (the same one-line install as [Instrument your product](/instrument-quickstart)).
3. One of the checkout hand-offs below.

No redirects and no link shortener: a partner's link is your own URL with `?via=<token>`.

---

## 1. Partner links

Every partner gets a link like:

```text
https://yourapp.com/?via=jane
```

When someone lands on any page carrying `?via=` (or `?ref=`), the script records the click and remembers the referral in a first-party cookie for the campaign's window (60 days by default). Clicks from search engines and from domains you blocked are not counted.

- **Sub-ids:** `https://yourapp.com/?via=jane&sub=youtube` tags the referral for the partner's own reporting.
- **Vanity links:** a partner can have more than one token, each landing on a different page (`/pricing?via=jane-yt`). Create them in the dashboard or with `POST /affiliates/{id}/links`.
- **First or last click:** set per program. With first click, a second partner's link does not take over a referral that is still inside its window.

### Extra parameter names

Moving from another affiliate tool whose links use a different parameter? Keep old links working by listing the names on the script tag:

```html
<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…"
        data-ref-params="fpr,aff"></script>
```

### Several domains

Marketing site on `yourapp.com` and checkout on `app.yourapp.io`? List the other domains and the script adds `?referral=<id>` to links pointing there, so the visit carries over:

```html
<script async src="https://app.ranla.ai/t.js?key=stxk_…" data-key="stxk_…"
        data-ref-domains="app.yourapp.io"></script>
```

### Pages without a link

To credit a partner on a page they did not link to (a dedicated landing page, a partner-specific pricing page), call:

```js
stx.referralSource('jane')
```

---

## 2. Record the signup

After someone signs up, tell the script who they are. This turns the anonymous click into a **lead** tied to their email:

```js
stx.identify({ email: user.email })
// or, the same thing under the name other affiliate tools use:
stx.referralSignup(user.email)
```

Call it on signup (and on login, which is harmless). If the campaign pays a lead bounty, the partner earns it when this signup makes their first payment.

No browser in the loop — a mobile app, an invite flow, a form handled entirely on your server? Record the referral with the API instead:

```bash
curl -X POST https://api.ranla.ai/affiliate-referrals \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"jane","email":"new-customer@example.com"}'
```

See [Affiliates API → Server-side referral tracking](/affiliates#server-side-referral-tracking).

---

## 3. Hand the referral to Stripe

Once the person pays, Stripe is where the commission comes from. Any **one** of these links a Stripe customer to the referral. They are checked in this order, and the first partner to claim a customer keeps them.

### Stripe Payment Links — automatic

Links to `https://buy.stripe.com/…` on a page with the script get `client_reference_id` added for you. Nothing to wire.

### Stripe Checkout — `client_reference_id`

`window.stx.referral` holds the current referral id (an empty string when there is none). Pass it when you create the Checkout Session. Wait for it with `stx.ready`:

```js
stx.ready(async () => {
  const res = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ priceId, referral: window.stx.referral }),
  })
  window.location = (await res.json()).url
})
```

```ts
// server
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: priceId, quantity: 1 }],
  client_reference_id: referral || undefined,
  success_url: 'https://yourapp.com/welcome',
})
```

### Custom subscriptions — `metadata.ranla_referral`

Creating customers or subscriptions yourself? Put the referral id (or the partner's link token) in metadata on the customer, subscription or invoice:

```ts
await stripe.customers.create({
  email,
  metadata: { ranla_referral: referral },
})
```

### Server-rendered forms — hidden inputs

The script fills any input marked `data-stx-referral` with the referral id, so it arrives with the form post:

```html
<form method="post" action="/signup">
  <input type="email" name="email" />
  <input type="hidden" name="referral" data-stx-referral />
  <button>Start free trial</button>
</form>
```

Store it and pass it to Stripe as `client_reference_id` or `metadata.ranla_referral`.

### Same email

If none of the above is present, a Stripe customer whose email matches a lead's email is attributed to that lead.

### Coupon codes

Each partner can have their own promotion code (`JANE20`). A customer who pays with it is attributed to that partner even without a click — useful for podcasts, videos and offline mentions. On a page the partner linked to, `stx.coupon` holds the partner's code as `{ id, code, label }` (`stx.coupon.code` is the text to show) and `stx.affiliate` their name, so you can show "Jane's 20% discount is applied".

---

## Excluding payments

Add `metadata.ranla = "false"` to a Stripe customer, subscription or invoice and it never earns a commission — for internal accounts, partner deals you pay separately, or refunds you settle by hand.

---

## What gets flagged

A referral is still recorded, but earns nothing, when:

- the person has the partner's own email, or the same company email domain (**self-referral**);
- the customer is already attributed to another partner (**duplicate**);
- the signup arrived after the cookie window ended (**expired**);
- the partner is suspended.

Flagged referrals show in the dashboard for review.

---

## Checking it works

1. Open `https://yourapp.com/?via=<a partner's token>` in a private window.
2. In the console, `stx.referral` should be a non-empty id.
3. Sign up with a test email. The partner's page in the dashboard shows the lead within a few seconds.
4. Pay with a Stripe test card. The commission appears after the next Stripe sync (every 15 minutes), `pending` until its hold ends.

Also see: [Affiliates API](/affiliates) · [Webhooks](/webhooks)

---

<!-- canonical: https://docs.ranla.ai/builders -->

# AI app builders

Use Ranla in Lovable, Replit, Bolt, Base44, v0, and similar AI builders.

**Two kinds of install surface:**

1. **Agent tools (MCP)** — the builder’s AI can call Ranla while you develop (Replit one-click MCP; Cursor/Claude via [MCP](../ai/mcp.md)).
2. **App runtime (Secrets + code)** — your deployed app sends mail via `RANLA_API_KEY` and `POST /emails` (or [SMTP](../api/smtp.md)).

Most guides below cover (2). Replit also has a one-click path for (1).

## Pick your builder

| Builder | Best for | Install surface |
|---------|----------|-----------------|
| [Lovable](/builders/lovable) | React + Supabase apps, chat-driven features | Secrets + agent prompt (HTTP or SMTP) |
| [Replit](/builders/replit) | Full-stack Replit Agent projects | MCP badge + Secrets + agent prompt |
| [Bolt.new](/builders/bolt) | Vite / React prototypes from chat | `.env` + agent prompt |
| [Base44](/builders/base44) | Base44 apps with optional custom email | When to use Ranla vs built-in mail |
| [v0](/builders/v0) | Next.js from Vercel v0 | Route Handler + Vercel env |

## Before you paste a prompt

1. Create a [Ranla account](https://app.ranla.ai) and an API key (`rnl_…`).
2. Store it as **`RANLA_API_KEY`** in the builder’s secrets / env UI (server-side only).
3. For a first send before your domain verifies, use the sandbox rules in [Quickstart](../quickstart.md) and [Agent skill notes](../ai/agent-skill.md).

## Standard env var

```bash
RANLA_API_KEY=rnl_your_key_here
```

Some builders also accept `STX_API_KEY` — if their UI suggests that name, map it to the same `rnl_…` value. Prefer `RANLA_API_KEY` in generated code for consistency with our SDK and docs.

## Reference

- [Agent skill notes](../ai/agent-skill.md) — integration defaults for AI agents
- [OpenAPI](../openapi.yaml) — API contract
- [Next.js](../frameworks/nextjs.md) — server-side send pattern
- [Auth provider email](../guides/auth-provider-email.md) — Clerk / Auth.js hooks
- [Supabase Auth email](../guides/supabase.md) — Send Email hook + Edge Function

---

<!-- canonical: https://docs.ranla.ai/builders/lovable -->

# Ranla + Lovable

Lovable’s install surface is **Secrets + a chat prompt**: store your `rnl_` key, paste the prompt, and let Lovable wire server-side sends (often via Supabase Auth).

There is no separate Lovable “connector package.” The agent writes the Edge Function / hook against `POST /emails` (or [SMTP](../api/smtp.md) if you prefer Supabase’s custom SMTP UI).

## When to use Ranla

- Password reset, verification, receipts, and other **transactional** mail
- Branded `from` on your own domain after DNS verify
- Supabase Auth via a Send Email hook / Edge Function, or [custom SMTP](../api/smtp.md) with a Ranla credential

Lovable projects often use Supabase — see [Supabase Auth email](../guides/supabase.md) for the hook path and the SMTP alternative.

## 1. Add your API key (Secrets)

1. Open [app.ranla.ai](https://app.ranla.ai) → **Settings → API keys** → create a key (`rnl_…`).
2. In Lovable, open your project **Settings** → **Secrets** (or the env/secrets panel Lovable exposes for backend code).
3. Add:

```text
RANLA_API_KEY=rnl_your_key_here
```

Use the secret name exactly — server routes and Edge Functions should read `process.env.RANLA_API_KEY`. Never put the key in client-side React components.

## 2. Paste this prompt in Lovable chat

```text
Integrate Ranla transactional email into this app.

Docs (read first):
- https://docs.ranla.ai/guides/supabase
- https://docs.ranla.ai/ai/agent-skill
- https://docs.ranla.ai/openapi.yaml
- https://docs.ranla.ai/builders/lovable
- https://docs.ranla.ai/smtp

Rules:
1. Store the API key in RANLA_API_KEY (already in Lovable Secrets). Never expose rnl_ keys in the browser.
2. Prefer POST https://api.ranla.ai/emails with Authorization: Bearer $RANLA_API_KEY (Supabase Edge Function or server route).
3. Alternative: configure Supabase custom SMTP with Ranla (host smtp.supersendtx.com, username supersendtx, password from dashboard SMTP credentials).
4. Until domain verification and Free production unlock (both required: verified domain + payment method on file), sandbox sends must use from "noreply@mail.ranla.ai" and to only our account email.
5. Add a server-side send path for password-reset / verification email.
6. Use canonical fields: html, text, reply_to. Prefer npm package supersendtx if the backend is Node.

After domain verify + payment method on file (Free production, no charge until upgrade), switch from to noreply@ourdomain.com.
```

Replace “our account email” with the email on your Ranla account if the agent asks.

## 3. Minimal server send (Node / Edge)

```ts
const res = await fetch('https://api.ranla.ai/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RANLA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'noreply@yourdomain.com',
    to: 'user@example.com',
    subject: 'Verify your email',
    html: '<p>Click the link to verify.</p>',
  }),
})
```

Or install `supersendtx` and use the SDK — see [Next.js](../frameworks/nextjs.md).

## Sandbox self-test

Send to your Ranla account email only, with `from: "noreply@mail.ranla.ai"`, until your domain is verified and Free production is unlocked (payment method on file):

```json
{
  "from": "noreply@mail.ranla.ai",
  "to": "YOUR_ACCOUNT_EMAIL",
  "subject": "Ranla sandbox check",
  "html": "<p>It works.</p>"
}
```

## Production

1. Add your domain in the Ranla dashboard.
2. Apply DNS (Cloudflare integration or registrar credentials).
3. Verify, add a payment method to unlock Free production (no charge until you upgrade), then update `from` to an address on that domain.

## Optional: MCP while you build

If you use Cursor (or another MCP client) alongside Lovable, connect hosted MCP at `https://mcp.ranla.ai/mcp` with OAuth — see [MCP server](../ai/mcp.md). That helps the coding agent; your Lovable app still needs Secrets (or SMTP) for runtime sends.

## Links

- [Quickstart](../quickstart.md)
- [Domains API](../api/domains.md)
- [SMTP relay](../api/smtp.md)
- [MCP server](../ai/mcp.md)
- [Password reset guide](../guides/password-reset-emails.md)
- [Supabase Auth email](../guides/supabase.md)

---

<!-- canonical: https://docs.ranla.ai/builders/replit -->

# Ranla + Replit

Two install surfaces, depending on the job:

| Surface | Use when |
|---------|----------|
| **MCP (Agent tools)** | Replit Agent should call Ranla (send, domains, templates) while building |
| **Secrets + app code** | Your running repl sends mail (password reset, invites, notifications) |

Most projects use both: MCP while building, Secrets for production paths in the app.

## Add to Replit (MCP)

One-click install of the hosted MCP server (`https://mcp.ranla.ai/mcp`). Replit uses OAuth — no API key in the link.

[![Install Ranla](https://replit.com/badge?caption=Install%20Ranla)](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlJhbmxhIiwiYmFzZVVybCI6Imh0dHBzOi8vbWNwLnJhbmxhLmFpL21jcCJ9)

Or open: [Add Ranla MCP](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlJhbmxhIiwiYmFzZVVybCI6Imh0dHBzOi8vbWNwLnJhbmxhLmFpL21jcCJ9)

After install, authorize with your Ranla account when prompted. Full MCP docs: [MCP server](../ai/mcp.md).

## Wire email into your app (Secrets)

### 1. Add your API key

1. Create an API key at [app.ranla.ai](https://app.ranla.ai) (`rnl_…`).
2. In Replit, open **Tools** → **Secrets** (or **Integrations** → secrets, depending on Replit UI).
3. Create a secret:

| Key | Value |
|-----|-------|
| `RANLA_API_KEY` | `rnl_your_key_here` |

Replit injects secrets as environment variables. Access via `process.env.RANLA_API_KEY` (Node) or `os.environ["RANLA_API_KEY"]` (Python). Never expose the key to the client.

### 2. Paste this prompt in Replit Agent

```text
Integrate Ranla transactional email into this Replit project.

Docs:
- https://docs.ranla.ai/ai/agent-skill
- https://docs.ranla.ai/openapi.yaml
- https://docs.ranla.ai/builders/replit
- https://docs.ranla.ai/ai/mcp

Rules:
1. Read RANLA_API_KEY from Replit Secrets (already configured). Never log or expose the key to the client.
2. Send with POST https://api.ranla.ai/emails and Authorization: Bearer <key>.
3. Until domain verification and Free production unlock (both required: verified domain + payment method on file), use from "noreply@mail.ranla.ai" and send only to the Ranla account email.
4. Implement server-side email for at least one flow (welcome, reset, or notification).
5. Use html and text fields; prefer supersendtx npm package on Node.

For production: verify a domain, add a payment method to unlock Free production (no charge until you upgrade), then set from to an address on that domain. Upgrade to Pro or Scale for more volume.
```

### 3. Minimal Express route (Node)

```js
import express from 'express'

const app = express()
app.use(express.json())

app.post('/api/send-test', async (req, res) => {
  const apiKey = process.env.RANLA_API_KEY
  if (!apiKey) return res.status(500).json({ error: 'Missing RANLA_API_KEY' })

  const upstream = await fetch('https://api.ranla.ai/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(req.body),
  })

  const data = await upstream.json()
  res.status(upstream.status).json(data)
})
```

## Sandbox self-test

Send to your Ranla account email only, with `from: "noreply@mail.ranla.ai"`, until your domain is verified and Free production is unlocked (payment method on file).

## Production

1. Verify a sending domain in Ranla.
2. Add a payment method to unlock Free production (no charge until you upgrade), or upgrade for higher volume.
3. Set `from` to `noreply@yourdomain.com` (or similar on your verified domain).

## Links

- [MCP server](../ai/mcp.md)
- [Quickstart](../quickstart.md)
- [Node.js](../frameworks/node.md)
- [Errors](../errors.md)

---

<!-- canonical: https://docs.ranla.ai/builders/bolt -->

# Ranla + Bolt.new

Add transactional email to a Bolt-generated app with a `.env` secret and a chat prompt. Bolt often outputs Vite or React projects — keep sends on the server.

## When to use Ranla

- Bolt prototypes that need real password-reset or notification email
- Moving from demo to production with your own sending domain
- Replacing a `RESEND_API_KEY` pattern with Ranla (`RANLA_API_KEY`)

## 1. Add your API key

1. Get a key from [app.ranla.ai](https://app.ranla.ai).
2. In the Bolt project, add to **`.env`** (local) and your host’s env UI when you deploy:

```bash
RANLA_API_KEY=rnl_your_key_here
```

3. Ensure `.env` is in `.gitignore` — never commit `rnl_` keys.

If Bolt deploys to a platform with its own env panel (Netlify, Vercel, etc.), add the same variable there for production.

## 2. Paste this prompt in Bolt chat

```text
Integrate Ranla transactional email into this project.

Docs:
- https://docs.ranla.ai/ai/agent-skill
- https://docs.ranla.ai/openapi.yaml
- https://docs.ranla.ai/builders/bolt

Rules:
1. Use RANLA_API_KEY from .env on the server only — never in client bundles or VITE_ prefixed vars.
2. POST https://api.ranla.ai/emails with Authorization: Bearer and JSON body (from, to, subject, html).
3. Until domain verification and Free production unlock (verified domain + payment method on file), sandbox from "noreply@mail.ranla.ai", to account email only.
4. Add a small API route or serverless function for transactional sends; do not call the API from the browser.
5. If this is Next.js, follow the App Router server pattern in https://docs.ranla.ai/frameworks/nextjs

After domain verify + payment method on file, use from on our verified domain for Free production. Upgrade for more volume.
```

## 3. Server-only pattern

Bolt may generate a Vite SPA. Add a server endpoint (or deploy a small API route) that proxies to Ranla:

```ts
// Example: server handler (adapt to your Bolt stack)
export async function sendTransactionalEmail(payload: {
  to: string
  subject: string
  html: string
}) {
  const res = await fetch('https://api.ranla.ai/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RANLA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from: process.env.MAIL_FROM ?? 'noreply@yourdomain.com',
      ...payload,
    }),
  })
  if (!res.ok) throw new Error(await res.text())
  return res.json()
}
```

## Sandbox

Use `noreply@mail.ranla.ai` and your account email for the first test — see [Quickstart](../quickstart.md).

## Links

- [Migration from Resend](../migration.md) — field mapping if you started with Resend env names
- [Next.js](../frameworks/nextjs.md)

---

<!-- canonical: https://docs.ranla.ai/builders/base44 -->

# Ranla + Base44

Base44 apps can send email through built-in platform features. Use Ranla when you need **your own domain**, higher control over deliverability, or the same transactional stack as the rest of your product.

## When Base44 built-in email is enough

- Early prototypes and internal tools
- Low volume without a custom domain requirement
- Flows where Base44’s default sender is acceptable

## When to add Ranla

- Branded mail from `@yourdomain.com` after DNS verify
- Password reset / auth mail you want on owned transactional infrastructure
- Webhooks and delivery visibility via Ranla dashboard
- Consistent API across non-Base44 services (same `POST /emails` everywhere)

## 1. Add your API key

1. Create `rnl_…` at [app.ranla.ai](https://app.ranla.ai).
2. In Base44, add a project secret or environment variable (exact UI varies by Base44 project type):

```text
RANLA_API_KEY=rnl_your_key_here
```

Wire server-side code or automation steps to read that variable — never expose it in client-visible config.

## 2. Paste this prompt in Base44

```text
Add Ranla for transactional email in this Base44 app (instead of or alongside built-in email).

Docs:
- https://docs.ranla.ai/ai/agent-skill
- https://docs.ranla.ai/openapi.yaml
- https://docs.ranla.ai/builders/base44

Rules:
1. Use RANLA_API_KEY from project secrets — server-side only.
2. POST https://api.ranla.ai/emails with Bearer auth for transactional sends (reset, verify, receipts).
3. Sandbox until domain verify: from "noreply@mail.ranla.ai", to Ranla account email only.
4. Explain when built-in Base44 email is still fine vs when Ranla is required (custom domain, production volume).
5. Use html/text; verify domain in Ranla before production from addresses.

Link users to https://app.ranla.ai for domain setup.
```

## 3. HTTP send

```json
POST https://api.ranla.ai/emails
Authorization: Bearer rnl_…
Content-Type: application/json

{
  "from": "noreply@yourdomain.com",
  "to": "user@example.com",
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>"
}
```

## Production checklist

- [ ] Domain added and verified in Ranla
- [ ] `from` uses verified domain
- [ ] API key only in secrets, not in frontend
- [ ] Bounce/complaint handling via [webhooks](../api/webhooks.md) if needed

## Links

- [Quickstart](../quickstart.md)
- [Domains](../api/domains.md)
- [Auth provider email](../guides/auth-provider-email.md)

---

<!-- canonical: https://docs.ranla.ai/builders/v0 -->

# Ranla + v0 (Vercel)

v0 generates Next.js apps. Run Ranla from a **Route Handler or Server Action** and store `RANLA_API_KEY` in Vercel environment variables.

## When to use Ranla

- v0 apps deployed to Vercel that need password reset, magic links, or receipts
- Server Components / Route Handlers — same pattern as [Next.js](../frameworks/nextjs.md)
- Production sends from your verified domain

## 1. Add your API key

**Local** — `.env.local`:

```bash
RANLA_API_KEY=rnl_your_key_here
```

**Vercel** — Project → **Settings** → **Environment Variables**:

| Name | Environments |
|------|----------------|
| `RANLA_API_KEY` | Production, Preview, Development |

Redeploy after adding the variable.

## 2. Paste this prompt in v0 chat

```text
Integrate Ranla transactional email into this Next.js app.

Docs:
- https://docs.ranla.ai/ai/agent-skill
- https://docs.ranla.ai/frameworks/nextjs
- https://docs.ranla.ai/openapi.yaml
- https://docs.ranla.ai/builders/v0

Rules:
1. RANLA_API_KEY is server-only (process.env) — never use NEXT_PUBLIC_ for the API key.
2. Send via POST https://api.ranla.ai/emails or npm package supersendtx from a Route Handler / Server Action.
3. Sandbox: from "noreply@mail.ranla.ai", to account email only until domain verify.
4. Add app/api/... route or server action for at least one transactional email flow.
5. Use html, text, reply_to. Follow Next.js server patterns — no client-side rnl_ keys.

Document that Vercel env var RANLA_API_KEY must be set before deploy.
```

## 3. Route Handler example

Create `app/api/email/send/route.ts`:

```ts
import { NextResponse } from 'next/server'
import { Ranla } from '@supersend/ranla'

const tx = new Ranla(process.env.RANLA_API_KEY!)

export async function POST(request: Request) {
  const body = await request.json()
  const result = await tx.emails.send({
    from: body.from ?? 'noreply@yourdomain.com',
    to: body.to,
    subject: body.subject,
    html: body.html,
    text: body.text,
  })
  return NextResponse.json(result)
}
```

Install: `npm install @supersend/ranla`

## Sandbox

Until your domain verifies, test with the sandbox sender and your Ranla account email — see [Agent skill notes](../ai/agent-skill.md).

## Production

1. Verify domain in Ranla dashboard.
2. Set production `from` to your domain.
3. Confirm `RANLA_API_KEY` is set on Vercel Production.

## Links

- [Next.js guide](../frameworks/nextjs.md)
- [Quickstart](../quickstart.md)
- [OpenAPI](../openapi.yaml)

---

<!-- canonical: https://docs.ranla.ai/emails -->

# Emails

Send transactional email and list recent sends. Migrating from Resend? See [`docs/migration.md`](../migration.md).

---

## Send email

`POST /emails`

Send a transactional email from a verified domain.

Base URL: `https://api.ranla.ai`

---

## Authentication

```http
Authorization: Bearer rnl_…
```

API keys are created in the dashboard (**Settings → API keys**). Keys start with `rnl_`.

---

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `from` | `string` or `{ email, name? }` | Yes | Must be on a verified domain |
| `to` | `string` or `string[]` | Yes | Recipient(s) |
| `subject` | `string` | Yes | Subject line |
| `html` | `string` | No* | HTML body (`htmlBody` / `html_body` aliases accepted) |
| `text` | `string` | No* | Plain-text body (`textBody`, `text_body`, and `plain_body` aliases accepted) |
| `reply_to` | `string` or `string[]` | No | Reply-to address(es) (`replyTo` alias accepted) |
| `cc` | `string` or `string[]` | No | CC recipient(s) |
| `bcc` | `string` or `string[]` | No | BCC recipient(s) |
| `tags` | `{ name, value }[]` or object | No | Up to 10 key/value tags stored with the email |
| `headers` | `object` | No | Custom headers; dangerous transport headers are rejected |
| `attachments` | `array` | No | Up to 10 files, 10MB decoded each; executable/script extensions are blocked. Attachment aliases `filename`, `contentType`, `content`, and `contentId` are also accepted. |
| `scheduled_at` | `string` | No | ISO 8601 timestamp. Creates a scheduled email instead of sending immediately (`scheduledAt` alias accepted) |
| `unsubscribe` | `boolean` | No | Opt in to managed unsubscribe (see below). Off by default for transactional mail. |
| `category` | `string` | No | Optional override: `transactional`, `product`, or `newsletter`. Inherits from template when sending with a template. |

\* At least one of `html` or `text` is required.

### Managed unsubscribe (opt-in)

Pure transactional mail (password resets, receipts, security alerts) should leave `unsubscribe` off.

When `unsubscribe: true`, Ranla:

- Injects RFC 8058 `List-Unsubscribe` and `List-Unsubscribe-Post` headers (one-click unsubscribe)
- Replaces `{{unsubscribe_url}}` in `subject`, `html`, and `text` with a signed confirmation link
- Binds the link to the first `to` address for that message

When sending with a published template, the template's `unsubscribe_enabled` flag is used unless you pass `unsubscribe` explicitly on the send request. Product and newsletter templates auto-enable managed unsubscribe and support category-scoped opt-out — recipients can unsubscribe from that category without blocking transactional mail.

### Template categories

Templates have a `category` that controls preference management:

| Category | Unsubscribe behavior |
|----------|---------------------|
| `transactional` | Default. No category opt-out. Global suppression only. |
| `product` | Category-scoped opt-out (onboarding tips, upgrade nudges) |
| `newsletter` | Same mechanism as product, for broadcast-style mail |

Sends to recipients who opted out of a category return `422`:

```json
{
  "error": {
    "message": "One or more recipients opted out of this email category",
    "code": "validation_error",
    "details": {
      "category_unsubscribed": ["user@example.com"],
      "category": "product",
      "email_id": "msg_…"
    }
  }
}
```

Global suppressions return the same status with `details.suppressed` instead.

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Product updates",
  "html": "<p>Hi there.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
  "unsubscribe": true
}
```

### Example

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Hello from Ranla",
  "html": "<p>It works.</p>"
}
```

With display name:

```json
{
  "from": { "email": "you@yourdomain.com", "name": "Your App" },
  "to": ["user@example.com", "other@example.com"],
  "subject": "Hello",
  "html": "<p>Hi</p>",
  "text": "Hi",
  "reply_to": ["support@yourdomain.com"],
  "tags": [{ "name": "order_id", "value": "ord_123" }],
  "headers": { "X-Entity-ID": "ord_123" }
}
```

### Sandbox self-test

Before your own domain is verified, you can self-test with the shared sandbox domain:

```json
{
  "from": "noreply@mail.ranla.ai",
  "to": "owner@example.com",
  "subject": "Sandbox check",
  "html": "<p>Sandbox works.</p>"
}
```

The sandbox sender is limited to the account email attached to the API key owner.

After your domain is verified, you can also self-test **from your verified domain** on the free plan — still limited to the account email:

```json
{
  "from": "you@yourdomain.com",
  "to": "owner@example.com",
  "subject": "Verified domain check",
  "html": "<p>My domain works.</p>"
}
```

Add a payment method to unlock Free production (send to other recipients on your verified domain — no charge until you upgrade). Upgrade to Pro or Scale for more volume.

---

## Responses

### 200 — Accepted

```json
{
  "id": "msg_abc123…",
  "status": "sent"
}
```

Scheduled sends return:

```json
{
  "id": "msg_abc123…",
  "status": "scheduled"
}
```

`id` is a stable public message ID (`msg_…`). Use it to correlate webhook events and dashboard activity.

---

## Idempotency

Optional header on `POST /emails`:

```http
Idempotency-Key: order-123
```

Keys are scoped per account, retained for **24 hours**. Replays return the original response. Reusing a key with a different body returns **409** `idempotency_conflict`.

If the mail server was unavailable and did not take the message (**502** or **503**), the key is released, so retrying with the same key sends the email. If the mail server could not confirm the send (**504**: it timed out, the connection dropped, or the reply was unreadable), the email may still be delivered. The key keeps that response, so a retry with the same key returns the 504 instead of risking a duplicate. The email is recorded as `failed` because delivery was not confirmed, so resend with a new key only if a duplicate is acceptable.

```ts
await client.emails.send({ …, idempotencyKey: 'order-123' })
```

---

## Retrieve email

`GET /emails/{id}`

Returns one send by public id (`msg_…`).

```ts
const { email } = await client.emails.get('msg_abc123…')
```

---

## Resend

`POST /emails/{id}/resend`

Creates a **new** send from a previously stored email (same from/to/subject/body, tags, and headers). Returns a new `msg_…` id. Attachment bytes are not stored, so attachments are omitted.

Dashboard: Emails → **Resend** on any row.

SDK:

```ts
await client.emails.resend('msg_abc123…')
```

CLI:

```bash
supersendtx emails resend --id msg_abc123…
```

---

## Schedule, reschedule, and cancel

Add `scheduled_at` to `POST /emails` to store the message and enqueue it for later delivery:

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "subject": "Tomorrow",
  "html": "<p>See you tomorrow.</p>",
  "scheduled_at": "2026-08-01T12:00:00.000Z"
}
```

Scheduled emails can be updated only while their status is `scheduled`:

```http
PATCH /emails/msg_abc123…
```

```json
{ "scheduled_at": "2026-08-01T13:00:00.000Z" }
```

Cancel a scheduled email:

```json
{ "cancel": true }
```

SDK:

```ts
await client.emails.update('msg_abc123…', { scheduledAt: '2026-08-01T13:00:00.000Z' })
await client.emails.cancel('msg_abc123…')
```

CLI:

```bash
supersendtx emails cancel --id msg_abc123…
```

Scheduled sends store message bodies so the worker can send them later. Attachments are not supported on scheduled emails in v1 because raw attachment data is not stored.

---

## Batch send

`POST /emails/batch`

Send up to 100 emails in one request:

```json
{
  "emails": [
    {
      "from": "you@yourdomain.com",
      "to": "user@example.com",
      "subject": "Hello",
      "html": "<p>Hi</p>"
    }
  ]
}
```

The response is index-aligned:

```json
{
  "data": [
    { "index": 0, "id": "msg_abc123…", "status": "sent" }
  ]
}
```

Per-email validation or delivery failures are returned in that item’s `error`. Attachments are rejected for batch sends in v1.

SDK:

```ts
const result = await client.emails.batch([{ from, to, subject, html }])
```

---

## List emails

`GET /emails?limit=25&cursor=…`

Returns recent sends for the authenticated API key’s account. `limit` is 1–100 (default 25). Use opaque `cursor` / `next_cursor` for pagination.

Responses include rate-limit headers: `ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`.

### 200

```json
{
  "emails": [
    {
      "id": "msg_abc123…",
      "from": "you@yourdomain.com",
      "to": ["user@example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "subject": "Hello",
      "status": "delivered",
      "last_event": "delivered",
      "bounce_reason": null,
      "tags": [],
      "scheduled_at": null,
      "cancelled_at": null,
      "created_at": "2026-07-25T12:00:00.000Z",
      "sent_at": "2026-07-25T12:00:01.000Z",
      "delivered_at": "2026-07-25T12:00:05.000Z",
      "bounced_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

Status values: `queued`, `scheduled`, `sent`, `delivered`, `bounced`, `failed`, `cancelled`.

### SDK

```ts
const { emails, next_cursor } = await client.emails.list({ limit: 10 })
```

### Error format

All errors return:

```json
{
  "error": {
    "message": "Human-readable message",
    "code": "validation_error",
    "details": {}
  }
}
```

| Status | When |
|--------|------|
| 400 | Invalid JSON, missing fields, invalid `from` |
| 401 | Missing/invalid Bearer token or API key |
| 403 | `from` domain not verified, sandbox/verified-domain sender used for recipients outside the account email, or send to other recipients without Free production unlocked (payment method on file) |
| 409 | Idempotency key conflict |
| 422 | Recipient suppressed or opted out, or the mail server refused the message (`upstream_error`) |
| 429 | Free plan send limit (`plan_limit`) |
| 502 | Upstream mail delivery error |
| 503 | Mail delivery temporarily unavailable |
| 504 | Mail server could not confirm the send; the email may still be delivered |

### Attachment limits

- Maximum 10 attachments per non-batch, non-scheduled send
- Maximum 10MB decoded size per attachment
- Blocked filename extensions: `.exe`, `.bat`, `.cmd`, `.com`, `.scr`, `.js`, `.vbs`, `.dll`

---

## Examples

### curl

```bash
curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"you@yourdomain.com","to":"user@example.com","subject":"Hello","html":"<p>Hi</p>"}'
```

### Node.js

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hi</p>',
})
```

Throws `SuperSendTXError` on failure (`error.status`, `error.message`, `error.details`).

### CLI

```bash
supersendtx emails send \
  --from you@yourdomain.com \
  --to user@example.com \
  --subject "Hello" \
  --html "<p>Hi</p>" \
  --tag order_id=ord_123 \
  --schedule 2026-08-01T12:00:00.000Z
```

Requires `RANLA_API_KEY` or `--api-key`.

---

## OpenAPI

Machine-readable spec: [`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/domains -->

# Domains API

Manage sending domains, DNS verification, inbound receiving flags, tracking preferences, TLS mode, one-click DNS apply, and DMARC/BIMI guidance.

Base URL: `https://api.ranla.ai`

Auth:

```http
Authorization: Bearer rnl_...
```

---

## Create a domain

`POST /domains`

```bash
curl -X POST https://api.ranla.ai/domains \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "example.com" }'
```

Success response:

```json
{
  "domain": {
    "id": "d_123",
    "name": "example.com",
    "status": "pending",
    "created_at": "2026-07-26T00:00:00.000Z",
    "verified_at": null,
    "open_tracking": false,
    "click_tracking": false,
    "tls_mode": "opportunistic"
  },
  "records": [
    {
      "type": "TXT",
      "host": "_supersendtx.example.com",
      "value": "supersendtx-verify=...",
      "purpose": "Domain ownership"
    }
  ]
}
```

To request inbound receiving during creation, include `"inbound_enabled": true`. The response will also include `inbound_records` (MX) and `inbound_note`. Full receiving flow: [`docs/api/inbound.md`](./inbound.md).

Expected DNS records (after create syncs with the mail server):

- ownership TXT: `_supersendtx.example.com`
- DKIM TXT: selector host such as `ss-abc123._domainkey.example.com` with the real public key
- return-path CNAME: `rp.example.com` → `rp.supersendtx.com` (DNS only / not proxied)
- SPF include: `include:spf.supersendtx.com`
- DMARC starter record

Ranla registers the domain on the transactional mail server at create time and replaces placeholder DKIM with the real signing records before apply/verify.

### Cross-team claim conflict

If the domain is already attached to another Ranla team, the API returns **409** with claim instructions:

```json
{
  "error": {
    "message": "Domain already belongs to another Ranla team. Remove it from the current team or contact support to claim it.",
    "code": "conflict",
    "details": {
      "reason": "domain_claim_required",
      "domain": "example.com",
      "instructions": [
        "Ask the current Ranla team admin to remove the domain if you still have access.",
        "If you own the domain but no longer control the original team, contact support and include proof of DNS control."
      ]
    }
  }
}
```

---

## Get a domain

`GET /domains/{id}`

Returns the domain, required DNS records, inbound MX guidance, and best-effort DMARC/BIMI analysis:

```json
{
  "domain": {
    "id": "d_123",
    "name": "example.com",
    "status": "verified",
    "created_at": "2026-07-26T00:00:00.000Z",
    "verified_at": "2026-07-26T00:05:00.000Z",
    "open_tracking": true,
    "click_tracking": false,
    "tls_mode": "enforced",
    "inbound_enabled": true,
    "inbound_status": "active",
    "inbound_error": null
  },
  "records": [],
  "inbound_records": [
    {
      "type": "MX",
      "host": "example.com",
      "priority": 10,
      "value": "mx.supersendtx.com",
      "purpose": "Inbound receiving"
    }
  ],
  "inbound_note": "Inbound receiving requires pointing this hostname's MX record to our mail servers. That conflicts with any existing mailbox provider on the same hostname, so use a dedicated subdomain such as inbound.example.com when Google Workspace or Microsoft 365 should keep handling your main mailboxes.",
  "analysis": {
    "dmarc": {
      "host": "_dmarc.example.com",
      "configured": true,
      "record": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com",
      "policy": "quarantine",
      "rua": ["mailto:dmarc@example.com"],
      "guidance": "DMARC is enforced. Keep report mailboxes monitored and tighten alignment as you roll out BIMI."
    },
    "bimi": {
      "host": "default._bimi.example.com",
      "configured": false,
      "record": null,
      "location": null,
      "authority": null,
      "requires_dmarc_enforcement": false,
      "guidance": "Optional: add a BIMI record at default._bimi once your branded SVG logo and optional VMC are ready."
    }
  }
}
```

### DMARC/BIMI notes

- **DMARC** is recommended for every sending domain.
- **BIMI** is optional, but most mailbox providers expect DMARC enforcement (`p=quarantine` or `p=reject`) before BIMI is effective.
- `analysis` is advisory. It does not block sending, and it does not replace your own deliverability monitoring.

---

## Verify DNS

`POST /domains/{id}`

```json
{ "action": "verify" }
```

When ownership, SPF, DKIM, and the return-path CNAME are visible in public DNS, Ranla asks the mail server to re-check delivery DNS and marks the domain verified only when mail-server **DKIM** and **return-path** statuses are OK. That step activates customer-domain DKIM signing (`d=yourdomain`) so DMARC can pass. Without DKIM OK, mail would fall back to the shared pool signer.

DMARC is reported back but does not currently block verification. Re-running verify on an already-verified domain re-checks mail-server DKIM (useful after DNS propagation).

Success responses include:

```json
{
  "verified": true,
  "signing_ready": true,
  "mail_server_signing": {
    "dkim_ok": true,
    "return_path_ok": true,
    "dkim_status": "OK",
    "return_path_status": "OK"
  }
}
```

If public DNS looks correct but the mail server has not yet accepted the DKIM TXT or return-path CNAME, verify returns **400** with `mail_server_signing.dkim_ok` / `return_path_ok` reflecting the failure — wait for propagation and verify again.

---

## Apply DNS

`POST /domains/{id}`

### Cloudflare via stored dashboard token

```json
{
  "action": "apply",
  "provider": "cloudflare"
}
```

### Cloudflare via inline credentials

```json
{
  "action": "apply",
  "provider": "cloudflare",
  "credentials": {
    "apiToken": "cf_...",
    "zoneId": "..."
  }
}
```

### GoDaddy via one-time credentials

```json
{
  "action": "apply",
  "provider": "godaddy",
  "credentials": {
    "apiKey": "gd_key",
    "apiSecret": "gd_secret"
  }
}
```

You can also save GoDaddy credentials under **Settings → Integrations** and omit `credentials` on apply.

### Vercel via stored dashboard token

```json
{
  "action": "apply",
  "provider": "vercel"
}
```

The domain must use **Vercel nameservers**. For team-scoped domains, connect Vercel under **Settings → Integrations** with an optional team id, or pass `credentials.teamId` / `credentials.vercelTeamId` inline.

### Vercel via inline credentials

```json
{
  "action": "apply",
  "provider": "vercel",
  "credentials": {
    "apiToken": "vercel_...",
    "teamId": "team_..."
  }
}
```

Response shape:

```json
{
  "provider": "godaddy",
  "domain": "example.com",
  "results": [
    {
      "purpose": "SPF",
      "host": "example.com",
      "action": "merged",
      "detail": "v=spf1 include:spf.supersendtx.com ~all"
    }
  ]
}
```

---

## Update tracking, inbound, and TLS preferences

`PATCH /domains/{id}`

```bash
curl -X PATCH https://api.ranla.ai/domains/example.com \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_enabled": true,
    "open_tracking": true,
    "click_tracking": true,
    "tls_mode": "enforced"
  }'
```

Aliases `openTracking`, `clickTracking`, `tlsMode`, and `inboundEnabled` are also accepted.

### Inbound enablement

- `inbound_enabled: true` marks the domain for receiving.
- Before verification, inbound stays `pending`.
- After verification, Ranla activates inbound receiving and updates `inbound_status` to `active` or `error`.
- See [`docs/api/inbound.md`](./inbound.md) for received-email retrieval and `email.received` webhooks.

### TLS modes

- `opportunistic` — use TLS when the downstream mail path supports it.
- `enforced` — require TLS for the downstream mail path.

### Tracking and TLS preferences

`open_tracking`, `click_tracking`, and `tls_mode` are stored on the domain immediately when you update them.

When open or click tracking is enabled:

1. Ranla provisions a tracking domain for your hostname.
2. The domain detail response includes a **tracking CNAME** (`ps.yourdomain.com` → `track.supersendtx.com`).
3. Apply and verify DNS so the mail server can rewrite links and inject open pixels.
4. `tracking_dns.ok` in `GET /domains/{id}` reports whether the CNAME is live.

If delivery-side provisioning fails, settings are still saved but `tracking_error` or `tls_error` may be returned on `PATCH` with a customer-facing message (not raw infrastructure errors).

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.domains.create({ name: 'example.com' })
await client.domains.apply('example.com')
await client.domains.apply('example.com', { provider: 'vercel' })
await client.domains.apply('example.com', {
  provider: 'godaddy',
  credentials: {
    apiKey: process.env.GODADDY_API_KEY!,
    apiSecret: process.env.GODADDY_API_SECRET!,
  },
})
await client.domains.verify('example.com')

const detail = await client.domains.get('example.com')
const updated = await client.domains.update('example.com', {
  open_tracking: true,
  tls_mode: 'enforced',
})
```

---

## CLI

```bash
supersendtx domains add example.com
supersendtx domains apply example.com --provider cloudflare
supersendtx domains apply example.com --provider vercel
GODADDY_API_KEY=... GODADDY_API_SECRET=... supersendtx domains apply example.com --provider godaddy
supersendtx domains verify example.com
```

---

## Delete a domain

`DELETE /domains/{id}`

Removes the domain from your account and revokes sending authorization for that hostname.

```bash
supersendtx domains delete example.com
```

If upstream teardown fails, the domain is kept and the API returns **502**.

---

## Common errors

| Status | Meaning |
|--------|---------|
| 400 | invalid domain, DNS not ready, missing provider credentials |
| 401 | missing or invalid auth |
| 403 | domain limit reached |
| 404 | domain not found |
| 409 | domain already exists or is already claimed |
| 502 | Domain registration, teardown, or DNS provider API failed |

Full contract: [`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/webhooks -->

# Webhooks

Receive signed HTTP callbacks for email lifecycle events.

Base URL: `https://api.ranla.ai`

Manage endpoints in the dashboard (**Webhooks**) or via the API / SDK / CLI below.

---

## Authentication

```http
Authorization: Bearer rnl_…
```

Dashboard session cookies also work for browser requests to `/api/webhooks`.

---

## Supported events

| Event | When fired |
|-------|------------|
| `email.received` | An inbound email arrived on a receive-enabled domain; retrieve full content from `/received-emails/{id}` |
| `email.sent` | Ranla accepted the message for delivery |
| `email.delivered` | The message was delivered to the recipient mailbox provider |
| `email.delivery_delayed` | Delivery was delayed or temporarily held |
| `email.bounced` | Hard/soft bounce; recipient is auto-suppressed |
| `email.complained` | Recipient marked the message as spam/complaint |
| `email.opened` | Open pixel loaded when open tracking is on |
| `email.clicked` | Tracked link clicked when click tracking is on |
| `email.failed` | Delivery failed; permanent SMTP failures also auto-suppress the recipient |
| `email.suppressed` | Send blocked because a recipient is on the suppression list |
| `email.scheduled` | Email accepted with `scheduled_at` |
| `contact.unsubscribed` | Recipient completed a managed unsubscribe. `data.scope` is `all` (global suppression) or `category` (product/newsletter opt-out only) |
| `automation.started` | An active automation matched an incoming event and a run was created |
| `automation.step_completed` | One automation step completed successfully |
| `automation.completed` | A run finished all steps (or ended early on a false condition) |
| `automation.failed` | A run failed (send failure, timeout, validation, etc.) |
| `affiliate.created` | A partner joined, was invited, imported or created over the API |
| `affiliate.approved` | A partner became active |
| `affiliate.updated` | A partner's profile, campaign, payout method or status changed |
| `referral.created` | A partner's referral was recorded as a lead |
| `referral.converted` | A referral became a paying customer |
| `commission.created` | A commission was written (pending during its hold) |
| `commission.earned` | A commission's hold ended |
| `commission.reversed` | A commission was reversed (refund, dispute or by hand) |
| `commission.paid` | A commission was paid in a payout |
| `payout.created` | A partner payout was drafted |
| `payout.paid` | A partner payout went out |
| `payout.failed` | A partner payout failed |

Open/click tracking are domain settings (`open_tracking` / `click_tracking`) configured per domain.

Affiliate events and their payloads are described in [Affiliates → Webhooks](/affiliates#webhooks).

---

## Create endpoint

`POST /webhooks`

```json
{
  "url": "https://yourapp.com/webhooks/supersendtx",
  "events": ["email.delivered", "email.bounced"]
}
```

`events` is optional — defaults to all supported events.

### 200 — Created

```json
{
  "webhook": {
    "id": "clx…",
    "url": "https://yourapp.com/webhooks/supersendtx",
    "events": ["email.delivered", "email.bounced"],
    "enabled": true,
    "created_at": "2026-07-25T12:00:00.000Z",
    "updated_at": "2026-07-25T12:00:00.000Z"
  },
  "secret": "whsec_…"
}
```

Copy `secret` immediately — it is only returned once. Use it to verify incoming webhook signatures.

---

## List endpoints

`GET /webhooks`

Cursor pagination: `limit`, `cursor` → `{ webhooks, has_more, next_cursor }`.

---

## Retrieve endpoint

`GET /webhooks/{id}`

```json
{
  "webhook": {
    "id": "clx…",
    "url": "https://yourapp.com/webhooks/supersendtx",
    "events": ["email.delivered", "email.bounced"],
    "enabled": true,
    "created_at": "2026-07-25T12:00:00.000Z",
    "updated_at": "2026-07-25T12:00:00.000Z"
  }
}
```

---

## Update endpoint

`PATCH /webhooks/{id}`

```json
{
  "url": "https://yourapp.com/new-path",
  "events": ["email.bounced"],
  "enabled": false
}
```

All fields are optional.

---

## Delete endpoint

`DELETE /webhooks/{id}`

```json
{ "ok": true }
```

---

## Test sink

`POST /emails/test` (full-scope API key)

```json
{ "event": "email.bounced", "email_id": "msg_…", "deliver": true }
```

Builds a webhook payload (optionally for an existing email) and, when `deliver` is not `false`, enqueues delivery to your subscribed endpoints. Useful in CI.

---

## Incoming webhook payload

Ranla `POST`s JSON to your endpoint URL when a subscribed event occurs.

### Email event example

```json
{
  "type": "email.received",
  "created_at": "2026-07-25T12:05:00.000Z",
  "data": {
    "email_id": "inb_abc123…",
    "to": ["sales@inbound.example.com"],
    "from": "Sender <sender@example.com>",
    "subject": "Hello",
    "status": "received",
    "rcpt_to": "sales@inbound.example.com",
    "cc": [],
    "message_id": "<abc@example.com>",
    "in_reply_to": null,
    "references": [],
    "spam_status": "NotSpam",
    "attachment_count": 1,
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 48291
      }
    ],
    "received_at": "2026-07-25T12:04:59.000Z"
  }
}
```

For inbound events, attachment metadata is included but attachment bytes are not — fetch `/received-emails/{id}` for full bodies and base64 attachment data.

For bounces, `type` is `email.bounced`, `status` is `bounced`, and `bounce_reason` may contain a provider reason string.

### Automation event example

```json
{
  "type": "automation.step_completed",
  "created_at": "2026-07-26T12:05:00.000Z",
  "data": {
    "automation_id": "a1b2c3",
    "automation_name": "Welcome flow",
    "run_id": "r1s2t3",
    "status": "running",
    "event_name": "user.created",
    "step_index": 0,
    "step_type": "send_email",
    "error": null
  }
}
```

### Contact unsubscribe examples

Global unsubscribe (`scope: "all"`) adds the address to suppressions and blocks every send:

```json
{
  "type": "contact.unsubscribed",
  "created_at": "2026-08-02T12:05:00.000Z",
  "data": {
    "email": "user@example.com",
    "source": "unsubscribe",
    "scope": "all",
    "category": null,
    "category_label": null,
    "suppression_id": "sup_…",
    "category_opt_out_id": null,
    "email_id": "msg_…"
  }
}
```

Category opt-out (`scope: "category"`) stops product or newsletter mail only — transactional messages still send:

```json
{
  "type": "contact.unsubscribed",
  "created_at": "2026-08-02T12:05:00.000Z",
  "data": {
    "email": "user@example.com",
    "source": "unsubscribe",
    "scope": "category",
    "category": "product",
    "category_label": "product emails",
    "suppression_id": null,
    "category_opt_out_id": "opt_…",
    "email_id": "msg_…"
  }
}
```

Check `data.scope` (and `data.category` when scope is `category`) before treating the address as fully suppressed.

---

## Signature verification

Each delivery includes:

```http
SuperSendTX-Signature: t=1721908800,v1=abc123…
```

### SDK helper (preferred)

```ts
import { Ranla, verifyWebhookSignature } from '@supersend/ranla'

const ok = verifyWebhookSignature(secret, rawBody, request.headers.get('supersendtx-signature'))
// or:
const client = new Ranla(process.env.RANLA_API_KEY!)
client.webhooks.verify(secret, rawBody, header)
```

Verify by:

1. Read the raw request body as a string (before JSON parsing).
2. Parse `t` (Unix timestamp) and `v1` (hex HMAC) from the header.
3. Reject if `t` is more than 5 minutes from your server clock.
4. Compute `HMAC-SHA256(secret, "${t}.${rawBody}")` and compare to `v1` (constant-time).

Return `2xx` quickly from your handler. Failed deliveries are retried at **0s, 5s, 30s, 2m and 2m**.

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

const { webhook, secret } = await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/supersendtx',
})

const { webhooks } = await client.webhooks.list()
const one = await client.webhooks.get(webhooks[0].id)
await client.webhooks.update(one.webhook.id, { enabled: false })
await client.webhooks.delete(webhooks[0].id)
```

---

## CLI

```bash
supersendtx webhooks list
supersendtx webhooks create --url https://yourapp.com/hooks
supersendtx webhooks delete --id clx…
```

Requires `RANLA_API_KEY` or `--api-key`.

---

## OpenAPI

Machine-readable spec: [`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/templates -->

# Templates

Create reusable email templates with `{{variable}}` placeholders, then send with
`POST /emails` using `template: { id, variables }`.

Base URL: `https://api.ranla.ai`

---

## Authentication

```http
Authorization: Bearer rnl_…
```

Requires a **full**-scope API key (or dashboard session). Sending-scoped keys cannot manage templates.

---

## Model

| Field | Notes |
|-------|--------|
| `name` | Required; unique per account |
| `alias` | Optional unique handle (not empty, not starting with `rnl_` or `stx_`) |
| `status` | `draft` (default) or `published` |
| `format` | `html` (legacy) or `blocks` (visual builder document) |
| `subject` / `html` / `text` | Support `{{var}}` placeholders |
| `preheader` | Optional inbox preview text |
| `design` | TemplateDocument JSON when `format` is `blocks` |
| `variables` | Variable names (auto-extracted for blocks templates) |
| `published_version_id` | Immutable version used for sends |
| `unsubscribe_enabled` | When `true`, sends using this template inherit managed unsubscribe unless overridden per send |
| `category` | `transactional` (default), `product`, or `newsletter`. Product and newsletter support category-scoped opt-out |
| `warnings` | Non-blocking deliverability hints for `html` (e.g. SVG logos) |

Placeholders in **HTML** bodies are HTML-escaped when interpolated. Subject and text are not.

Publishing snapshots an immutable version. Sends always resolve `published_version_id`, so draft edits never break live aliases. See [docs/templates/builder.md](../templates/builder.md).

### Global CSS (`blocks` templates)

`design.settings.globalCss` accepts ordinary CSS that is compiled for the inbox on render:

- Rules whose selector is a bare tag (`body`, `p`, `h1`, `h2`, `h3`, `a`, `img`, `hr`) become
  **inline styles** on those elements and override per-block styling. Inlining matters because
  Gmail drops `<style>` on clipped and forwarded messages, and Outlook renders through Word.
- Everything else — class and id selectors, pseudo-classes, descendant selectors, media
  queries — is emitted into a `<style>` block, which most clients honour.

```json
{
  "design": {
    "version": 1,
    "settings": {
      "globalCss": "p { color: rgb(63,63,70); }\n@media (max-width: 480px) { p { font-size: 14px; } }"
    }
  }
}
```

`@import` is stripped, and CSS cannot inject markup.

### Images in HTML

Use **PNG or JPG** logos at **public `https://` URLs** in `<img src="…">` tags. Many inboxes (including Gmail) do not render SVG images. Ranla returns advisory `warnings` on template create/get/list when HTML may not render reliably — sends are not blocked.

```html
<img src="https://yourdomain.com/assets/logo.png" alt="Your product" width="36" height="36" />
```

---

## List

`GET /templates`

Query: `limit`, `cursor`, optional `status=draft|published`.

```json
{
  "data": [
    {
      "id": "…",
      "name": "Welcome",
      "alias": "welcome",
      "status": "published",
      "subject": "Hello {{name}}",
      "html": "<p>Hi {{name}}</p>",
      "text": "Hi {{name}}",
      "variables": ["name"],
      "published_at": "2026-07-26T12:00:00.000Z",
      "created_at": "2026-07-26T11:00:00.000Z",
      "updated_at": "2026-07-26T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

---

## Create

`POST /templates` → **201**

```json
{
  "name": "Welcome",
  "alias": "welcome",
  "subject": "Hello {{name}}",
  "html": "<p>Hi {{name}}</p>",
  "text": "Hi {{name}}",
  "variables": ["name"]
}
```

Creates a **draft**. Publish before sending.

---

## Starter catalog

`GET /templates/starters` — list copyable starters (full-scope key).

`POST /templates/from-starter` — copy one into your account as **published** with a fixed alias.

| Alias | Variables |
|-------|-----------|
| `password-reset` | `name`, `reset_url` |
| `email-verification` | `name`, `verify_url`, `code` |
| `welcome` | `name`, `dashboard_url` |
| `invoice` | `name`, `amount`, `invoice_url`, `invoice_id` |
| `team-invite` | `name`, `inviter_name`, `team_name`, `invite_url` |

```bash
curl -X POST https://api.ranla.ai/templates/from-starter \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias":"password-reset"}'
```

```ts
await client.templates.fromStarter('password-reset')
await client.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  template: {
    id: 'password-reset',
    variables: { name: 'Ada', reset_url: 'https://app.example.com/reset?token=…' },
  },
})
```

Dashboard: **Templates → Start from a template**. Returns **409** if the name or alias already exists on the account.

---

## Retrieve / update / delete

- `GET /templates/{id}` — UUID or alias
- `PATCH /templates/{id}` — update fields
- `DELETE /templates/{id}`

---

## Publish / duplicate

`POST /templates/{id}`

```json
{ "action": "publish" }
```

```json
{ "action": "duplicate", "name": "Welcome (copy)" }
```

Duplicate creates a new **draft** (alias cleared). `name` is optional (defaults to `… (copy)`).

---

## Send with a template

`POST /emails`

```json
{
  "from": "you@yourdomain.com",
  "to": "user@example.com",
  "template": {
    "id": "welcome",
    "variables": { "name": "Ada" }
  }
}
```

`template` is mutually exclusive with `html` / `text`. Subject comes from the template unless you pass `subject` to override. Only **published** templates can be used.

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

const { template } = await client.templates.create({
  name: 'Welcome',
  alias: 'welcome',
  subject: 'Hello {{name}}',
  html: '<p>Hi {{name}}</p>',
})
await client.templates.publish(template.id)

await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  template: { id: 'welcome', variables: { name: 'Ada' } },
})
```

### React Email (optional peer)

Install `@react-email/render` (and `react`) to pass a React element:

```bash
npm install @react-email/render react
```

```ts
await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  react: EmailComponent({ name: 'Ada' }),
})
```

The SDK compiles `react` to HTML before `POST /emails`. Mutually exclusive with `html` / `text` / `template`.

Full guide: [Send React Email](/guides/react-email).

---

## CLI

```bash
supersendtx templates list
supersendtx templates starters
supersendtx templates from-starter password-reset
supersendtx templates create --name Welcome --subject "Hi {{name}}" --html "<p>Hi {{name}}</p>" --alias welcome --category product --unsubscribe-enabled
supersendtx templates update --id welcome --category product --unsubscribe-enabled
```

### Push from your repo

`templates push` upserts a template from a local file, keyed by `--alias`, so your repo can be
the source of truth:

```bash
# HTML file
supersendtx templates push ./emails/welcome.html --alias welcome --subject "Welcome" --publish

# React Email component, rendered locally
supersendtx templates push ./emails/WelcomeEmail.tsx --alias welcome --props '{"name":"Ada"}' --publish
```

| Flag | Notes |
|------|-------|
| `<file>` | `.html`, `.txt`, or a module (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`) with a React component as its default export |
| `--alias` | Required. Creates the template on first push, updates it afterwards |
| `--subject` | Required only when creating |
| `--name` | Display name; defaults to the alias |
| `--preheader` | Inbox preview text |
| `--text <file>` | Attach a hand-written plain-text part |
| `--props <json>` | Props passed to the component when rendering |
| `--publish` | Cut a published version after pushing |

Module files are imported **in your process** and rendered with `@react-email/render` — only
the resulting HTML and text are uploaded. TypeScript and JSX need a loader: install `tsx`
(`npm install -D tsx`) or pre-render to `.html`. See
[React Email guide](../guides/react-email.md).

---

## OpenAPI

[`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/templates/builder -->

# Visual template builder

Non-technical teammates design emails in the dashboard builder. Engineers send with a stable alias:

```ts
await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  template: {
    id: 'welcome',
    variables: { name: 'Ada', dashboard_url: 'https://app.example.com' },
  },
})
```

## How it works

1. Create a template from **Templates**: use a starter, **Visual builder**, or **Paste HTML** for markup you already have.
2. Open **Edit** — block editor for `blocks` templates, or the raw HTML / plain-text editor for `html` templates (includes preheader and Test send).
3. Use `{{variable}}` placeholders in subject, copy, and button URLs.
4. **Publish** freezes an immutable version. Sends always use that version — draft edits never break live traffic.
5. Restore an older version from the API if you need to roll back the draft, then publish again.

## Formats

| Format | Meaning |
|--------|---------|
| `blocks` | Visual builder document (`design` JSON) compiled to email-safe HTML |
| `html` | Raw HTML/text — editable in the code editor; switching to the visual builder permanently deletes HTML (with confirmation) |

## Global CSS

`design.settings.globalCss` lets you style a whole template with ordinary CSS instead of
per-block controls. The **Global CSS** panel in the builder inspector edits it, and shows which
rules get inlined.

Rules whose selector is a bare tag — `body`, `p`, `h1`, `h2`, `h3`, `a`, `img`, `hr` — are merged
into those elements' `style` attributes on render, and override block styling. Everything else
(class and id selectors, pseudo-classes, descendant selectors, media queries) goes into a
`<style>` block.

The split is not a limitation of the parser; it is what survives the inbox. Gmail drops
`<style>` on clipped and forwarded messages, and Outlook renders through Word, so anything that
must be reliable has to be inline. Class selectors are still useful for markup inside an
`html` block.

`@import` is stripped and CSS cannot inject markup. The editable canvas does not preview global
CSS — switch to **Preview** for the exact render.

## Code view

The **Code** tab in the builder shows the exact HTML that publish stores and sends, with
`{{variable}}` placeholders left in place, plus a copy button. It is read-only for `blocks`
templates — the canvas and Global CSS are the inputs that produce it.

`format: 'html'` templates open in the same editor, writable, with separate HTML and plain-text
tabs.

## Keeping templates in git

`supersendtx templates push <file> --alias <alias>` upserts a template from a local `.html`,
`.txt`, or React Email component. Module files are imported and rendered in your process, so
only the resulting HTML and text are uploaded. See
[Templates API — CLI](../api/templates.md#cli) and the
[React Email guide](../guides/react-email.md).

## Versioning

- `POST /templates/{id}` with `{ "action": "publish" }` creates `EmailTemplateVersion` and points `published_version_id` at it. Each version stores an immutable `format` snapshot (`html` or `blocks`) so restoring an older version brings back the correct editor mode even if the live draft was converted.
- `GET /templates/{id}/versions` lists history.
- `POST /templates/{id}/versions/{n}` with `{ "action": "restore" }` loads that snapshot into the draft (does not auto-publish).

## Images

Prefer PNG/JPEG/WebP at absolute HTTPS URLs. When image storage is configured on the deployment, the builder can upload images via `POST /assets` (presigned PUT). Otherwise paste a public URL.

## Client compatibility

The blocks renderer emits table-based HTML with Outlook (MSO) conditionals, mobile stacking, dark-mode meta, bulletproof buttons, and a hidden preheader — the same output for live preview and publish.

---

<!-- canonical: https://docs.ranla.ai/events -->

# Events

Send custom events into Ranla to trigger transactional automations.

Base URL: `https://api.ranla.ai`

---

## Authentication

```http
Authorization: Bearer rnl_…
```

Dashboard session cookies also work for browser requests to `/api/events`, which is how the automations canvas editor sends test events.

---

## Trigger an event

`POST /events`

```json
{
  "name": "user.created",
  "user_id": "user_123",
  "email": "user@example.com",
  "data": {
    "name": "Ada Lovelace",
    "plan": "pro"
  }
}
```

`type` is accepted as an alias for `name`.

### Idempotency

Use `Idempotency-Key` for replay-safe retries:

```http
Idempotency-Key: evt_user_created_123
```

Retries with the same key and body return the original response. Reusing the key with a different body returns HTTP `409`.

Keys are kept for 24 hours. After that, the same key is accepted as a new event, so a key such as `user.activated:<userId>` does not make an event fire once per person. For once-only events, emit from the moment the state changes (the write that first sets `activatedAt`), or check a flag your app already stores.

### 202 Accepted

```json
{
  "event": {
    "id": "ae_123",
    "name": "user.created",
    "user_id": "user_123",
    "email": "user@example.com",
    "data": {
      "name": "Ada Lovelace",
      "plan": "pro"
    },
    "source": "api",
    "created_at": "2026-07-26T12:00:00.000Z"
  },
  "matched_automations": 2,
  "resumed_runs": 1,
  "cancelled_runs": 0
}
```

- `matched_automations` = active automations whose trigger matched this event
- `resumed_runs` = waiting runs resumed by this event (`wait_for_event`)
- `cancelled_runs` = active runs cancelled because this event matched `trigger.cancel_on_events`

---

## Event shape

| Field | Type | Notes |
|------|------|-------|
| `name` | string | Required unless `type` is provided |
| `type` | string | Alias for `name` |
| `user_id` | string | Optional identity hint for wait/resume matching |
| `email` | string | Optional identity hint for wait/resume matching |
| `data` | object | Optional event payload used by conditions and email templates |
| `dry_run` | boolean | Dashboard only — with `automation_id`, runs that one automation even if draft/paused; skips delays/waits and stubs email/SMS |
| `test_send` | boolean | Dashboard only — with `automation_id`, same targeting as dry-run but **sends real email/SMS**; still skips delays/waits. Mutually exclusive with `dry_run` |
| `automation_id` | string | Required with `dry_run` or `test_send`; rejected on API-key requests |

Inside automations, you can reference:

- `{{event.name}}`
- `{{event.email}}`
- `{{event.user_id}}`
- `{{event.data.foo}}`

**Credentials in `data`.** Automations triggered by the event see `data` exactly as you sent it, so a step can mail a login code with `{{event.data.code}}`. The stored copy of the event is redacted: values under credential keys (`password`, `secret`, `otp`, `api_key`, anything ending in `token`, and `code` on login or verification events such as `auth.code_requested`), plus secret query parameters inside URL values, are stored as `"REDACTED"`. The `event` in the response shows the stored copy. Segments and event reports read the stored copy, so they can never match on a credential.

---

## Typical flow

1. Create an automation (dashboard canvas, `POST /automations`, or `supersendtx automations create`) with trigger `user.created`
2. Activate it (`POST /automations/{id}` with `{ "action": "activate" }`)
3. Send `POST /events` from your app when that business event happens
4. Ranla queues the run in Bull/Redis
5. Send-email steps flow through the same transactional send path as `POST /emails`

See also [`docs/api/automations.md`](./automations.md).

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.events.trigger({
  name: 'user.created',
  user_id: 'user_123',
  email: 'user@example.com',
  data: { name: 'Ada Lovelace' },
  idempotencyKey: 'evt_user_created_123',
})
```

---

## CLI

```bash
RANLA_API_KEY=$RANLA_API_KEY npx -y --package=ranla-cli -- ranla events send \
  --name user.created \
  --email user@example.com \
  --user-id user_123 \
  --data '{"name":"Ada Lovelace"}'
```

---

## OpenAPI

Machine-readable spec: [`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/conversions -->

# Conversions

Record that a conversion goal happened, and list conversions already attributed to a campaign.

A goal is what winning is — a purchase, a page visit, a survey response, a waitlist signup, or a qualified lead. You create the goal in the dashboard. This API records conversions against its key.

Base URL: `https://api.ranla.ai`

---

## Authentication

```http
Authorization: Bearer rnl_…
```

---

## Goal types

Only a `revenue` goal stores money. The others are count-only: `value_cents` is always `0`, even if you send an amount.

| Type | What winning is | `value_cents` |
|------|-----------------|---------------|
| `revenue` | Money changed hands | Stored |
| `visit` | They reached a page | Always 0 |
| `feedback` | They answered a survey | Always 0 |
| `waitlist` | They asked to be let in | Always 0 |
| `qualify` | They proved they are a prospect | Always 0 |

---

## Record

`POST /conversions`

Identify the person with at least one of `click_id`, `contact_id`, or `email`. `click_id` is the `stx_cid` value on campaign links — the strongest signal. Recording a conversion never creates a contact.

Omit `goal` to use the account's primary goal.

Idempotent on `(goal, external_id)`: send the same `external_id` twice and the second call returns the first conversion with `duplicate: true`.

```json
{
  "goal": "revenue",
  "email": "ada@example.com",
  "value_cents": 4900,
  "currency": "usd",
  "external_id": "ch_123"
}
```

Count-only — no amount:

```json
{
  "goal": "waitlist",
  "email": "ada@example.com"
}
```

```json
{
  "conversion": {
    "id": "conv_1",
    "goal_id": "goal_1",
    "contact_id": null,
    "email": "ada@example.com",
    "value_cents": 0,
    "currency": "usd",
    "external_id": null,
    "source": "api",
    "occurred_at": "2026-09-05T12:00:00.000Z",
    "attributed_campaign_id": "camp_1",
    "attributed_variant_id": "var_A",
    "attributed_recipient_id": "rcp_1",
    "attribution_kind": "click",
    "created_at": "2026-09-05T12:00:00.000Z"
  },
  "duplicate": false
}
```

`attribution_kind` is how the conversion was tied to a campaign, strongest first: `click`, `open`, `send`, or `none`.

---

## List

`GET /conversions`

Query: `limit`, `cursor`, optional `goal`, `goal_id`, `campaign_id`, `email`.

```json
{
  "data": [],
  "has_more": false,
  "next_cursor": null
}
```

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.conversions.create({
  goal: 'revenue',
  email: 'ada@example.com',
  value_cents: 4900,
  external_id: 'ch_123',
})

await client.conversions.create({
  goal: 'waitlist',
  email: 'ada@example.com',
})

const { data } = await client.conversions.list({ goal: 'waitlist' })
```

---

## CLI

```bash
supersendtx conversions record --goal revenue --email ada@example.com --value-cents 4900 --external-id ch_123
supersendtx conversions record --goal waitlist --email ada@example.com
supersendtx conversions list --goal waitlist
```

---

## OpenAPI

[`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/automations -->

# Automations

Create and manage event-driven transactional automations with a Bearer `rnl_…` API key (or dashboard session).

Base URL: `https://api.ranla.ai`

You can also build flows visually in the dashboard canvas under **Automations**.

---

## Authentication

```http
Authorization: Bearer rnl_…
```

---

## Create an automation

`POST /automations`

Creates a **draft**. Activate it before events will match.

```json
{
  "name": "Welcome email",
  "trigger": {
    "type": "event",
    "event": "user.created"
  },
  "steps": [
    {
      "type": "send_email",
      "email": {
        "from": "you@yourdomain.com",
        "to": "{{event.email}}",
        "subject": "Welcome",
        "html": "<p>Hi {{event.data.name}}</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>"
      }
    }
  ]
}
```

Examples below are generated from `src/lib/dx/snippets.ts` (same source as the dashboard).

### curl

```bash
curl -X POST https://api.ranla.ai/automations \
  -H "Authorization: Bearer rnl_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Welcome email","trigger":{"type":"event","event":"user.created"},"steps":[{"type":"send_email","email":{"from":"you@yourdomain.com","to":"{{event.email}}","subject":"Welcome","html":"<p>Hi {{event.data.name}}</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>"}}]}'
```

### npm

```ts
npm install @supersend/ranla

import { Ranla } from '@supersend/ranla'

const client = new Ranla('rnl_…')

const { automation } = await client.automations.create({
  name: 'Welcome email',
  trigger: { type: 'event', event: 'user.created' },
  steps: [
    {
      type: 'send_email',
      email: {
        from: 'you@yourdomain.com',
        to: '{{event.email}}',
        subject: 'Welcome',
        html: '<p>Hi {{event.data.name}}</p><p><a href="{{unsubscribe_url}}">Unsubscribe</a></p>',
      },
    },
  ],
})

await client.automations.activate(automation.id)
```

### CLI

```bash
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla automations create --file ./welcome.json
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla automations activate --id "$AUTOMATION_ID"
```

`welcome.json` should match the request body above.

---

## Endpoints

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/automations` | List |
| `POST` | `/automations` | Create draft |
| `GET` | `/automations/{id}` | Get |
| `PATCH` | `/automations/{id}` | Update name/trigger/steps |
| `DELETE` | `/automations/{id}` | Delete |
| `POST` | `/automations/{id}` | `{ "action": "activate" \| "pause" }` |
| `GET` | `/automations/runs` | Optional `?automation_id=` |
| `GET` | `/automations/runs/{id}` | Run detail |
| `POST` | `/automations/runs/{id}` | `{ "action": "cancel" \| "retry" }` |

---

## Step types

| Type | Purpose |
|------|---------|
| `send_email` | Send via the same transactional send path as `POST /emails` — inline `subject`/`html` **or** a published [`email.template`](./templates.md) |
| `send_sms` | Send SMS via [Twilio](./integrations.md) — requires a connected integration and `sms.to` + `sms.body` |
| `delay` | Wait `seconds` before the next step |
| `condition` | Continue only if true; **false stops the run** (not if/else branching) |
| `wait_for_event` | Pause until another event arrives (optional `timeout_seconds`; `on_timeout` `continue` or `fail`, default `fail`) |

**Trigger options:**

| Key | Meaning |
|-----|---------|
| `cancel_on_events` | Array of event names that cancel queued, running, or waiting runs for the same recipient when fired. |
| `once_per_contact` | `true` to enrol each person at most once, ever (matched on the event's `email` or `user_id`). A second matching event is skipped and reported in the `POST /events` response as `enrollment_skips` with `reason: "once_per_contact"`. |
| `cooldown_days` | Integer 1–3650. Skip enrolment when the same person already had a run on this automation within the last N days (`reason: "cooldown"`). |

Dashboard dry-runs and test sends are never deduplicated, and a `retry` of a failed run bypasses both rules. The check and the enrolment run inside one transaction under an advisory lock keyed on the automation and the person, so two copies of the same event arriving at once (a retried webhook, two workers) still enrol once.

**Placeholders** in email and SMS steps, in any string:

| Placeholder | Resolves to |
|-------------|-------------|
| `{{event.email}}`, `{{event.user_id}}`, `{{event.data.foo}}` | The triggering event. |
| `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`, `{{contact.status}}`, `{{contact.attributes.plan}}` | The contact matched by the event's email or `user_id` (→ `external_id`), loaded **when the step runs**. |
| `{{contact_at_enrollment.attributes.plan}}` | The same snapshot, frozen when the run was created. |
| `{{unsubscribe_url}}` | The managed unsubscribe link (product / newsletter category). |

A Liquid-style default is accepted: `{{contact.first_name | default:"there"}}`. An unresolved placeholder renders as empty text, never as literal braces.

**Conditions on the contact:** a `condition` step whose `path` starts with `contact.` reads the contact fresh at step time, so a 14-day delay followed by `{ "type": "condition", "path": "contact.attributes.subscribed", "operator": "not_equals", "value": true }` means "still not subscribed when the step runs". On `contact.` and `contact_at_enrollment.` paths, `equals` / `not_equals` compare **as text**, the same way segments do: booleans and numbers are stringified, so `"value": true` and `"value": "true"` both match an attribute stored as `true` or `"true"` (attributes are JSON written by whichever integration last touched the contact, and the stored type is not visible to the author). A missing contact or attribute equals only `null`. Event paths (`event.data.*`) stay strict, because the payload is typed by your own code. `contact_at_enrollment.` paths read the frozen snapshot.

**Category and unsubscribe:** inline `send_email` steps default to `"category": "product"` — the send honours product opt-outs, carries `List-Unsubscribe` headers, and replaces `{{unsubscribe_url}}` in `html` and `text` with the managed link. The placeholder is replaced, never appended, so include it; the API returns a `warnings` array when a product/newsletter step has none. Set `"category": "transactional"` only for genuinely transactional mail (receipts, OTPs). Template-backed steps inherit the template's category unless `category` is set on the step. A recipient who opted out of the category completes the run with a `category_opt_out` step output instead of failing it.

```json
{
  "name": "Signup → still free after 14 days",
  "trigger": { "type": "event", "event": "signup", "cancel_on_events": ["subscription_checkout"], "once_per_contact": true },
  "steps": [
    { "type": "delay", "seconds": 1209600 },
    { "type": "condition", "path": "contact.attributes.subscribed", "operator": "not_equals", "value": true },
    {
      "type": "send_email",
      "email": {
        "from": "you@yourdomain.com",
        "to": "{{event.email}}",
        "subject": "Two weeks in",
        "html": "<p>Hey {{contact.first_name | default:\"there\"}},</p><p>…</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
        "text": "Hey {{contact.first_name | default:\"there\"}},\n\n…\n\nUnsubscribe: {{unsubscribe_url}}"
      }
    }
  ]
}
```

**Conversions:** a conversion whose last touch inside the goal window was a send from an automation is credited to it (`attributed_automation_id` / `attributed_run_id` on the conversion). `GET /automations/{id}` returns `conversions: { total, revenue_cents, mix }`; `GET /conversions?automation_id=` lists them.

### SMS example (`send_sms`)

Connect Twilio first ([`integrations twilio connect`](./integrations.md)), then create an automation:

```json
{
  "name": "Auth OTP (SMS)",
  "trigger": { "type": "event", "event": "auth.code_requested" },
  "steps": [
    {
      "type": "send_sms",
      "sms": {
        "to": "{{event.data.phone}}",
        "body": "Your code is {{event.data.code}}. Expires in 10 min."
      }
    }
  ]
}
```

```bash
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla integrations twilio connect \
  --account-sid AC… --auth-token … --from +15551234567
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla automations create --file ./otp-sms.json
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla automations activate --id "$AUTOMATION_ID"
```

Template example (mutually exclusive with inline `subject` / `html` / `text`):

```json
{
  "type": "send_email",
  "email": {
    "from": "you@yourdomain.com",
    "to": "{{event.email}}",
    "template": {
      "id": "welcome",
      "variables": { "name": "{{event.data.name}}" }
    }
  }
}
```

---

## Trigger the flow

After activate, send events with [`POST /events`](./events.md) or:

```bash
supersendtx events send --name user.created --email user@example.com --data '{"name":"Ada"}'
```

---

<!-- canonical: https://docs.ranla.ai/integrations -->

# Integrations

Connect third-party services used by automations and DNS workflows — Twilio for SMS steps, plus Vercel and related account integrations for domain tooling.

Base URL: `https://api.ranla.ai`

Auth: Bearer `rnl_…` **full-access** API key (or dashboard session cookie). Sending-scoped keys cannot manage integrations.

---

## Twilio (SMS)

Required before `send_sms` automation steps will deliver.

### Get status

`GET /integrations/twilio`

```bash
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla integrations twilio status
```

Response (never includes raw credentials):

```json
{
  "twilio": {
    "connected": true,
    "hint": "aaaa",
    "connectedAt": "2026-01-01T00:00:00.000Z",
    "defaultFrom": "+15551234567",
    "messagingServiceSid": null
  }
}
```

### Connect

`PUT /integrations/twilio`

Validates Account SID + Auth Token against Twilio, encrypts them at rest, and stores a default `from` number and/or Messaging Service SID for `send_sms` steps.

```bash
RANLA_API_KEY=rnl_… npx -y --package=ranla-cli -- ranla integrations twilio connect \
  --account-sid AC… \
  --auth-token … \
  --from +15551234567
```

Or set env vars and omit flags:

```bash
export TWILIO_ACCOUNT_SID=AC…
export TWILIO_AUTH_TOKEN=…
export TWILIO_DEFAULT_FROM=+15551234567
supersendtx integrations twilio connect
```

Use `--messaging-service-sid MG…` instead of `--from` when you send via a Twilio Messaging Service.

### npm

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla('rnl_…')

await client.integrations.connectTwilio({
  accountSid: 'AC…',
  authToken: '…',
  defaultFrom: '+15551234567',
})

const { twilio } = await client.integrations.getTwilio()
console.log(twilio.connected)
```

### Disconnect

`DELETE /integrations/twilio`

```bash
supersendtx integrations twilio disconnect
```

---

## Cloudflare (DNS)

Session cookie auth only (dashboard **Settings → Integrations**). For terminal DNS apply, pass `CLOUDFLARE_API_TOKEN` to [`domains apply`](./domains.md) instead, or rely on the stored dashboard token.

---

## Vercel (DNS)

Session cookie auth only (dashboard **Settings → Integrations**). Save an API token and optional team id for domains that use **Vercel nameservers**. For terminal DNS apply, pass `VERCEL_API_TOKEN` and optional `VERCEL_TEAM_ID` to [`domains apply`](./domains.md), or rely on the stored dashboard token.

### Get status

`GET /integrations/vercel`

### Connect

`PUT /integrations/vercel`

```json
{
  "apiToken": "vercel_…",
  "teamId": "team_…"
}
```

### Disconnect

`DELETE /integrations/vercel`

---

<!-- canonical: https://docs.ranla.ai/api-keys -->

# API keys

Manage Ranla API keys from the public API (Bearer auth with a **full**-scope key) or the dashboard (**Settings → API keys**).

Base URL: `https://api.ranla.ai`

---

## Scopes

| Scope | Access |
|-------|--------|
| `full` (default) | Every endpoint. Keys created in the dashboard are full. |
| `sending` | For your app's server: send and read your email (`/emails`, `/emails/batch`, cancel, reschedule, resend), `GET /deliverability`, `POST /events`, and `POST /conversions`. |

A `sending` key gets `403` everywhere else: reading contacts, lists, or conversions, and managing domains, webhooks, templates, automations, suppressions, integrations, or keys.

---

## List

`GET /api-keys?limit=25&cursor=…`

```json
{
  "data": [
    {
      "id": "…",
      "name": "Default",
      "scope": "full",
      "prefix": "rnl_abcd",
      "created_at": "2026-07-26T00:00:00.000Z",
      "last_used_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

---

## Create

`POST /api-keys`

```json
{ "name": "CI", "scope": "sending" }
```

Response (token shown once):

```json
{
  "id": "…",
  "name": "CI",
  "scope": "sending",
  "prefix": "rnl_…",
  "token": "rnl_…",
  "created_at": "2026-07-26T00:00:00.000Z"
}
```

---

## Delete

`DELETE /api-keys/{id}` → `{ "ok": true }`

Cannot delete the key authenticating the request.

---

## SDK / CLI

```ts
await client.apiKeys.create({ name: 'CI', scope: 'sending' })
await client.apiKeys.list()
await client.apiKeys.remove(id)
```

```bash
supersendtx keys create --name CI --scope sending
supersendtx keys list
supersendtx keys delete --id <id>
```

---

<!-- canonical: https://docs.ranla.ai/suppressions -->

# Suppressions

Block sends to addresses that bounced, complained, or were added manually. Suppressions are **tenant-local** to your Ranla account.

Base URL: `https://api.ranla.ai`

---

## Authentication

```http
Authorization: Bearer rnl_…
```

Requires a **full**-scope API key (or dashboard session). Sending-scoped keys cannot manage suppressions.

---

## Behavior

- Emails are stored **normalized lowercase**.
- Hard bounces, permanent SMTP delivery failures (e.g. invalid mailbox / 5xx), and complaint-like events auto-add suppressions (`source: bounce` / `complaint`).
- Managed unsubscribe links add suppressions with `source: unsubscribe`.
- `POST /emails` checks `to` / `cc` / `bcc` before sending. If any recipient is suppressed, the API returns **422** with `code: validation_error`, `details.suppressed`, and emits `email.suppressed` (a `suppressed` email record is created).

---

## List

`GET /suppressions`

Query: `limit`, `cursor`, optional `email`.

```json
{
  "data": [
    {
      "id": "…",
      "email": "bad@example.com",
      "reason": "550 user unknown",
      "source": "bounce",
      "created_at": "2026-07-26T12:00:00.000Z",
      "updated_at": "2026-07-26T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

---

## Add

`POST /suppressions`

```json
{ "email": "user@example.com", "reason": "manual opt-out" }
```

`source` is set to `api`. Upserts on `(account, email)`.

---

## Remove

`DELETE /suppressions/{id}`

or

`DELETE /suppressions?email=user@example.com`

```json
{ "ok": true }
```

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.suppressions.create({ email: 'user@example.com', reason: 'opt-out' })
const { data } = await client.suppressions.list()
await client.suppressions.remove('user@example.com')
```

---

## CLI

```bash
supersendtx suppressions list
supersendtx suppressions add --email user@example.com --reason "opt-out"
supersendtx suppressions remove --email user@example.com
```

---

## OpenAPI

[`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/inbound -->

# Inbound email API

Receive mail on a verified Ranla domain, get `email.received` webhooks, and retrieve full inbound messages with attachments.

Base URL: `https://api.ranla.ai`

Auth:

```http
Authorization: Bearer rnl_...
```

---

## Overview

Inbound receiving is configured on the existing **domain** resource:

1. Create a domain with `inbound_enabled: true` or enable it later with `PATCH /domains/{id}`.
2. Verify the domain (`POST /domains/{id}` with `{ "action": "verify" }`).
3. Publish the returned MX record so Ranla can receive mail for that hostname.
4. Subscribe to `email.received` webhooks or poll `/received-emails`.

Ranla stores:

- the inbound message headers/bodies
- attachment metadata on list responses
- full attachment base64 data on retrieve responses

---

## Important MX conflict note

Inbound receiving requires changing the domain hostname's **MX** record to Ranla.

That means:

- if `example.com` already receives mail at Google Workspace, Microsoft 365, Fastmail, etc, moving the MX record will stop that provider from receiving new mail for `example.com`
- the safest pattern is usually a dedicated subdomain such as `inbound.example.com`

Every domain detail/create response includes:

- `inbound_records` — the MX record to publish
- `inbound_note` — the same warning in machine-readable responses

---

## Create a receiving domain

`POST /domains`

```bash
curl -X POST https://api.ranla.ai/domains \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "inbound.example.com",
    "inbound_enabled": true
  }'
```

Response:

```json
{
  "domain": {
    "id": "d_123",
    "name": "inbound.example.com",
    "status": "pending",
    "created_at": "2026-07-26T00:00:00.000Z",
    "verified_at": null,
    "open_tracking": false,
    "click_tracking": false,
    "tls_mode": "opportunistic",
    "inbound_enabled": true,
    "inbound_status": "pending",
    "inbound_error": null
  },
  "records": [
    {
      "type": "TXT",
      "host": "_supersendtx.inbound.example.com",
      "value": "supersendtx-verify=...",
      "purpose": "Domain ownership"
    }
  ],
  "inbound_records": [
    {
      "type": "MX",
      "host": "inbound.example.com",
      "priority": 10,
      "value": "mx.supersendtx.com",
      "purpose": "Inbound receiving"
    }
  ],
  "inbound_note": "Inbound receiving requires pointing this hostname's MX record to our mail servers. That conflicts with any existing mailbox provider on the same hostname, so use a dedicated subdomain such as inbound.example.com when Google Workspace or Microsoft 365 should keep handling your main mailboxes."
}
```

`inbound_status: "pending"` means inbound receiving finishes setup after verification succeeds.

---

## Enable inbound on an existing domain

`PATCH /domains/{id}`

```bash
curl -X PATCH https://api.ranla.ai/domains/inbound.example.com \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inbound_enabled": true }'
```

If the domain is already verified, Ranla immediately activates inbound receiving for that hostname.

Relevant fields:

- `domain.inbound_status = "active"` — inbound receiving is configured
- `domain.inbound_status = "pending"` — waiting for verification
- `domain.inbound_status = "error"` + `domain.inbound_error` — inbound setup failed and should be retried

---

## Verify the domain

`POST /domains/{id}`

```json
{ "action": "verify" }
```

If `inbound_enabled` is already `true`, verification also activates inbound receiving and returns:

- `inbound_configured`
- `inbound_pending`
- `inbound_error`

---

## List received emails

`GET /received-emails`

Optional query params:

- `limit`
- `cursor`
- `domain` — receiving domain name

```bash
curl https://api.ranla.ai/received-emails?domain=inbound.example.com \
  -H "Authorization: Bearer $RANLA_API_KEY"
```

Response:

```json
{
  "received_emails": [
    {
      "id": "inb_abc123",
      "domain_id": "d_123",
      "domain_name": "inbound.example.com",
      "status": "received",
      "rcpt_to": "sales@inbound.example.com",
      "mail_from": "sender@example.org",
      "from": "Sender <sender@example.org>",
      "to": ["sales@inbound.example.com"],
      "cc": [],
      "subject": "Question about pricing",
      "spam_status": "NotSpam",
      "bounced": false,
      "received_with_ssl": true,
      "message_id": "<abc@example.org>",
      "in_reply_to": null,
      "references": [],
      "attachment_count": 1,
      "attachments": [
        {
          "filename": "invoice.pdf",
          "content_type": "application/pdf",
          "size": 48291
        }
      ],
      "text_body": null,
      "html_body": null,
      "auto_submitted": null,
      "received_at": "2026-07-26T12:00:00.000Z",
      "created_at": "2026-07-26T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

List responses omit attachment `data` and null out message bodies to keep payloads smaller.

---

## Retrieve a received email

`GET /received-emails/{id}`

```bash
curl https://api.ranla.ai/received-emails/inb_abc123 \
  -H "Authorization: Bearer $RANLA_API_KEY"
```

Response:

```json
{
  "received_email": {
    "id": "inb_abc123",
    "domain_id": "d_123",
    "domain_name": "inbound.example.com",
    "status": "received",
    "rcpt_to": "sales@inbound.example.com",
    "mail_from": "sender@example.org",
    "from": "Sender <sender@example.org>",
    "to": ["sales@inbound.example.com"],
    "cc": [],
    "subject": "Question about pricing",
    "spam_status": "NotSpam",
    "bounced": false,
    "received_with_ssl": true,
    "message_id": "<abc@example.org>",
    "in_reply_to": null,
    "references": [],
    "attachment_count": 1,
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 48291,
        "data": "JVBERi0xLjQKJ..."
      }
    ],
    "text_body": "Hello there!",
    "html_body": "<p>Hello there!</p>",
    "auto_submitted": null,
    "received_at": "2026-07-26T12:00:00.000Z",
    "created_at": "2026-07-26T12:00:00.000Z"
  }
}
```

Attachments are base64 encoded.

---

## `email.received` webhook

Subscribe a webhook endpoint to `email.received` with `POST /webhooks`.

Webhook deliveries include metadata only, not full attachment data:

```json
{
  "type": "email.received",
  "created_at": "2026-07-26T12:00:01.000Z",
  "data": {
    "email_id": "inb_abc123",
    "to": ["sales@inbound.example.com"],
    "from": "Sender <sender@example.org>",
    "subject": "Question about pricing",
    "status": "received",
    "rcpt_to": "sales@inbound.example.com",
    "cc": [],
    "message_id": "<abc@example.org>",
    "in_reply_to": null,
    "references": [],
    "spam_status": "NotSpam",
    "attachment_count": 1,
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "size": 48291
      }
    ],
    "received_at": "2026-07-26T12:00:00.000Z"
  }
}
```

Retrieve the full message from `/received-emails/{id}` when you need bodies or attachment bytes.

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.domains.create({
  name: 'inbound.example.com',
  inbound_enabled: true,
})

await client.domains.verify('inbound.example.com')

const { received_emails } = await client.receivedEmails.list({
  domain: 'inbound.example.com',
})

const one = await client.receivedEmails.get(received_emails[0].id)
```

---

## CLI

```bash
supersendtx domains add inbound.example.com --inbound true
supersendtx domains verify inbound.example.com
supersendtx domains update inbound.example.com --inbound true
supersendtx received-emails list --domain inbound.example.com
supersendtx received-emails get inb_abc123
```

---

## OpenAPI

Machine-readable spec: [`openapi/supersendtx.yaml`](../../openapi/supersendtx.yaml)

---

<!-- canonical: https://docs.ranla.ai/deliverability -->

# Deliverability API

Best-effort deliverability insights computed from the email rows and webhook events Ranla already stores.

Base URL: `https://api.ranla.ai`

Auth:

```http
Authorization: Bearer rnl_...
```

---

## Get insights

`GET /deliverability?window=30d`

Supported windows:

- `7d`
- `30d` (default)

Example:

```bash
curl -X GET "https://api.ranla.ai/deliverability?window=7d" \
  -H "Authorization: Bearer $RANLA_API_KEY"
```

Response:

```json
{
  "window": "7d",
  "window_start": "2026-07-19T00:00:00.000Z",
  "generated_at": "2026-07-26T00:00:00.000Z",
  "summary": {
    "total_emails": 10,
    "attempted": 9,
    "sent": 8,
    "delivered": 7,
    "bounced": 1,
    "failed": 1,
    "suppressed": 1,
    "scheduled": 0,
    "opened": 3,
    "clicked": 1,
    "bounce_rate": 0.1111,
    "delivery_rate": 0.7778,
    "open_rate": 0.4286,
    "click_rate": 0.1429
  },
  "by_domain": [],
  "top_bounce_reasons": [],
  "notes": [
    "Best-effort metrics only"
  ]
}
```

---

## What this includes

- attempted vs scheduled/suppressed counts
- delivered and bounced counts
- best-effort open/click counts from stored events
- breakdown by sending domain
- top recorded bounce reasons
- optional `mail_server_relay` on top domains when relay metrics are available (relay-side sent/bounce/fail counts)

## Roadmap

These are not exposed in the API yet:

- inbox placement / spam folder data
- provider reputation and reputation trends
- richer bounce classifications beyond stored events

---

## SDK

```ts
const insights = await client.emails.insights('30d')
```

## CLI

```bash
supersendtx emails insights --window 7d
```

---

<!-- canonical: https://docs.ranla.ai/smtp -->

# SMTP relay

Send mail through Ranla using standard SMTP — for Supabase custom SMTP, Clerk, WordPress, Nodemailer, and other integrations that expect host, username, and password.

The relay uses the **same account scoping, domain verification, sandbox rules, billing, suppressions, and webhooks** as `POST /emails`.

---

## Connection settings

| Setting | Value |
|---------|--------|
| Host | `smtp.supersendtx.com` |
| Port | `587` (STARTTLS) |
| Username | `supersendtx` |
| Password | Your SMTP credential (`stxsmtp_…`) |

Create credentials in the dashboard under **SMTP** or via `POST /smtp-credentials` with a full-access API key.

The password is shown **once** at creation — copy it immediately.

---

## Create a credential

```bash
curl -X POST https://api.ranla.ai/smtp-credentials \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supabase production"}'
```

Response includes `host`, `port`, `username`, and `password`.

---

## Supabase custom SMTP

After you verify your domain in Ranla:

1. Dashboard → **SMTP** → **Create SMTP credential**
2. Supabase → **Project Settings → Authentication → SMTP**
3. Paste host, port, username `supersendtx`, password, and your branded sender email

For hook-based auth mail (Edge Functions), see [Supabase Auth email](/guides/supabase).

---

## Nodemailer example (SMTP)

For the HTTP Nodemailer transport (no SMTP credential), see [Node.js](/frameworks/node).

```js
import nodemailer from 'nodemailer'

const transport = nodemailer.createTransport({
  host: 'smtp.supersendtx.com',
  port: 587,
  secure: false,
  auth: {
    user: '@supersend/ranla',
    pass: process.env.SUPERSENDTX_SMTP_PASSWORD,
  },
})

await transport.sendMail({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Hi</p>',
  headers: {
    'X-SuperSendTX-Tag': 'campaign=welcome',
    'X-SuperSendTX-Idempotency-Key': 'welcome-123',
    // 'X-SuperSendTX-Scheduled-At': '2030-01-01T00:00:00Z',
  },
})
```

---

## Custom headers (API features over SMTP)

The relay maps these headers onto `POST /emails` fields so SMTP clients are not limited to basic MIME:

| Header | Maps to |
|--------|---------|
| `X-SuperSendTX-Tag` | `tags` (`name=value`; repeat for multiple) |
| `X-SuperSendTX-Idempotency-Key` or `Idempotency-Key` | Idempotency (24h, same rules as HTTP) |
| `X-SuperSendTX-Scheduled-At` | `scheduled_at` (ISO 8601) |

Other non-reserved headers are forwarded to the API `headers` object.

---

## Rules

- `From` must use a **verified domain** for your account (or sandbox rules apply)
- Revoke credentials from the dashboard or `DELETE /smtp-credentials/{id}`
- SMTP credentials are **send-only** — use API keys for management APIs
- If mail delivery is briefly unavailable, the relay replies **451** so your client keeps the message and retries. Other failures reply **554** and should not be retried, including a timeout where the email may still be delivered.

---

## Local development

Run the SMTP relay worker:

```bash
npm run build:worker
npm run worker:smtp
```

Default bind: `0.0.0.0:2525` (plain SMTP, no TLS). Set `SUPERSENDTX_SMTP_PORT` to override.

---

## Related

- [Emails API](/emails)
- [Supabase Auth email](/guides/supabase)
- [Auth provider email](/guides/auth-provider-email)

---

<!-- canonical: https://docs.ranla.ai/affiliates -->

# Affiliates

Run your affiliate and customer referral program from code: add partners, hand them links, record referrals from your server, sign partners in to their portal, and read the commission ledger and payouts.

Base URL: `https://api.ranla.ai`

Set up the program first in the dashboard (**Affiliates**): turn it on, connect Stripe and pick a commission. The API works on that program. For the browser side (links, checkout, signups) see the [affiliate tracking guide](/guides/affiliate-tracking).

---

## Authentication

```http
Authorization: Bearer rnl_…
```

Every affiliate endpoint needs a **full access** key. A sending key gets `403`.

---

## Resources

| Resource | Endpoints |
|----------|-----------|
| Partners | `GET/POST /affiliates` · `GET/PATCH/DELETE /affiliates/{id}` · `POST /affiliates/{id}/approve` · `/reject` · `/suspend` |
| Links | `GET/POST /affiliates/{id}/links` · `DELETE /affiliates/{id}/links/{link_id}` |
| Portal sign-in (SSO) | `POST /affiliates/{id}/login-link` |
| Campaigns | `GET/POST /affiliate-campaigns` · `GET/PATCH /affiliate-campaigns/{id}` |
| Referrals | `GET/POST /affiliate-referrals` · `GET /affiliate-referrals/{id}` |
| Commissions | `GET /affiliate-commissions` · `GET/PATCH /affiliate-commissions/{id}` |
| Payouts | `GET /affiliate-payouts` · `GET /affiliate-payouts/{id}` · `POST /affiliate-payouts/{id}/mark-paid` |

Money is always in minor units (`amount_cents`), with a lowercase `currency`. Rates are basis points: `2000` is 20%.

**Payout runs are not approved over the API.** Approving a run moves money, so it stays with the account owner in the dashboard (or the approval card in Slack). The API can read payouts and mark manual ones paid once their run is approved.

### Lists and pagination

List endpoints return newest first:

```json
{ "data": [ … ], "has_more": true, "next_cursor": "eyJ0Ijoi…" }
```

Pass `limit` (1–100, default 25) and `cursor=<next_cursor>` for the next page. Closed-set filters take a comma-separated list: `?status=active,pending`.

### Errors

The standard error body. Validation errors name each bad field under `details.fields`:

```json
{
  "error": {
    "message": "\"jane\" is already taken",
    "code": "conflict",
    "details": { "fields": { "token": "Already taken" } }
  }
}
```

| Status | `code` | When |
|--------|--------|------|
| 400 | `validation_error` | A field is missing or invalid, or an action does not fit the partner's status |
| 401 | `unauthorized` | Missing or invalid key |
| 403 | `forbidden` | Sending key, or the action is not allowed (deleting a paid partner, a primary link) |
| 404 | `not_found` | Not in this account, or the program is not set up yet |
| 409 | `conflict` | Email already a partner, token taken, or the row changed in the meantime |

---

## Partners

### The partner object

```json
{
  "object": "affiliate",
  "id": "5b0c…",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "company": null,
  "website": null,
  "country": "US",
  "status": "active",
  "source": "api",
  "campaign_id": "a41e…",
  "parent_affiliate_id": null,
  "tags": ["customer"],
  "payout_method": "paypal",
  "payout_ready": true,
  "approved_at": "2026-09-25T10:00:00.000Z",
  "links": [
    {
      "object": "affiliate_link",
      "id": "9f2d…",
      "affiliate_id": "5b0c…",
      "token": "jane",
      "url": "https://yourapp.com/?via=jane",
      "destination_url": null,
      "label": null,
      "is_primary": true,
      "created_at": "2026-09-25T10:00:00.000Z"
    }
  ],
  "created_at": "2026-09-25T10:00:00.000Z",
  "updated_at": "2026-09-25T10:00:00.000Z"
}
```

`status` is one of `invited`, `pending`, `active`, `suspended`, `rejected`. Single-partner responses list every link; lists carry the primary link only.

### Create a partner

`POST /affiliates`

| Field | Type | Notes |
|-------|------|-------|
| `email` | string | Required. One partner per email. |
| `first_name`, `last_name`, `company`, `website`, `country` | string | Optional. `country` is a 2-letter code. |
| `campaign_id` | string | Campaign id or name. The default campaign when omitted. |
| `token` | string | Their link token (`?via=jane`). Kept exactly, or `409` when taken. Derived from the name when omitted. |
| `status` | string | `active` (default), `pending` (needs approval) or `invited`. |
| `paypal_email` | string | Where PayPal payouts go. |
| `tags` | string[] | Up to 20. |
| `notes` | string | Private to your team. |
| `send_invite` | boolean | Send the welcome email (default `true`). Set `false` when your app shows the link itself. |

**Customer referral programs.** Turn signed-in customers into referrers from inside your app — create the partner the first time they open your "Refer a friend" page and show them their link:

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

async function referralLinkFor(user: { email: string; name: string }) {
  const found = await client.affiliates.list({ email: user.email })
  const partner =
    found.data[0] ??
    (await client.affiliates.create({
      email: user.email,
      first_name: user.name,
      tags: ['customer'],
      send_invite: false,
    })).affiliate
  return partner.links?.[0]?.url
}
```

```bash
curl -X POST https://api.ranla.ai/affiliates \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","first_name":"Jane","token":"jane","send_invite":false}'
```

`201` → `{ "affiliate": { … } }`

### List, get, update, delete

- `GET /affiliates?status=active&campaign_id=…&email=…` — `email` is an exact lookup.
- `GET /affiliates/{id}`
- `PATCH /affiliates/{id}` — `first_name`, `last_name`, `company`, `website`, `country`, `notes`, `tags`, `campaign_id` (new commissions use the new campaign's rate), `parent_affiliate_id`, `postback_url`, `email_opt_out`, `commission_override` (`{ "commission_type": "percent", "commission_bps": 3000 }`, or `null` to clear), and `token` (renames the primary link; the old link stops attributing).
- `DELETE /affiliates/{id}` — refused with `403` once the partner has been paid. Suspend them instead.

### Approve, reject, suspend

```bash
curl -X POST https://api.ranla.ai/affiliates/$ID/approve \
  -H "Authorization: Bearer $RANLA_API_KEY"
```

| Endpoint | From → to | Body |
|----------|-----------|------|
| `POST /affiliates/{id}/approve` | `pending`, `invited`, `rejected` → `active` | `send_email` (default `true`) |
| `POST /affiliates/{id}/reject` | `pending`, `invited` → `rejected` | `reason`, `send_email` |
| `POST /affiliates/{id}/suspend` | `active`, `pending`, `invited` → `suspended` | `reason` |

A suspended partner's links stop attributing and payouts skip them.

### Links

- `GET /affiliates/{id}/links`
- `POST /affiliates/{id}/links` — `{ "token": "jane-youtube", "destination_url": "/pricing", "label": "YouTube" }`. `destination_url` is a path or a page on your website. Up to 50 links per partner.
- `DELETE /affiliates/{id}/links/{link_id}` — the primary link cannot be deleted.

### Sign partners in to the portal (SSO)

`POST /affiliates/{id}/login-link`

```json
{ "object": "affiliate_login_link", "url": "https://acme.partners.ranla.ai/auth/callback?token=…", "expires_at": "2026-09-25T10:01:00.000Z" }
```

The link signs the partner in to your partner portal once and expires after **one minute**. Mint it when a signed-in user clicks "Referral dashboard" in your app and redirect straight away — never email or store it:

```ts
app.get('/referrals/dashboard', requireUser, async (req, res) => {
  const { url } = await client.affiliates.loginLink(req.user.affiliateId)
  res.redirect(url)
})
```

Rejected partners cannot sign in (`403`).

---

## Campaigns

A campaign is a commission plan. Every partner belongs to one; the default campaign takes new partners.

```json
{
  "object": "affiliate_campaign",
  "id": "a41e…",
  "name": "Standard",
  "is_default": true,
  "visibility": "public",
  "auto_approve": true,
  "commission_type": "percent",
  "commission_bps": 3000,
  "commission_flat_cents": 0,
  "commission_duration": "recurring",
  "recurring_months": 12,
  "max_commission_cents": null,
  "tiers": [{ "min_paid_customers": 10, "commission_bps": 4000, "commission_flat_cents": null }],
  "product_rates": [],
  "second_tier_bps": 0,
  "lead_bounty_cents": 0,
  "cookie_days": 60,
  "hold_days": 30,
  "archived_at": null,
  "created_at": "…",
  "updated_at": "…"
}
```

- `GET /affiliate-campaigns?include_archived=true` — not paged; each row adds `affiliate_count`.
- `POST /affiliate-campaigns` — `name` is required; pass `make_default: true` to make it the default.
- `GET /affiliate-campaigns/{id}`, `PATCH /affiliate-campaigns/{id}` — new rates apply to new commissions only.

`recurring_months: null` pays for the customer's lifetime. `hold_days` is the refund window before a commission is earned. `tiers` raise the rate once a partner has brought that many paying customers. `second_tier_bps` pays a partner's recruiter a share of the same sale.

---

## Referrals

A referral is a person a partner sent you. It starts as a `lead` and becomes `active` when they pay (`trialing`, `cancelled`, `refunded` and `rejected` follow the customer).

```json
{
  "object": "affiliate_referral",
  "id": "c7a0…",
  "affiliate_id": "5b0c…",
  "status": "lead",
  "source": "api",
  "email": "new-customer@example.com",
  "stripe_customer_id": "cus_Q…",
  "sub_id": null,
  "blocked_reason": null,
  "revenue_cents": 0,
  "currency": "usd",
  "converted_at": null,
  "expires_at": "2026-11-24T10:00:00.000Z",
  "created_at": "…",
  "updated_at": "…"
}
```

`GET /affiliate-referrals` filters: `status`, `source`, `affiliate_id`, `email`, `created_after`, `created_before`.

### Server-side referral tracking

`POST /affiliate-referrals` attributes a person to a partner without the browser snippet — for example from a signup handler that received a referral code in a mobile app, an invite flow, or your own `?ref=` handling.

| Field | Notes |
|-------|-------|
| `affiliate_id` or `token` | Required, one of them. `token` is the partner's link token. |
| `email` | Required. The referred person. |
| `stripe_customer_id` | Optional. Ties their future Stripe payments to this referral straight away. |
| `sub_id` | Optional tag for reporting. |

```bash
curl -X POST https://api.ranla.ai/affiliate-referrals \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"jane","email":"new-customer@example.com","stripe_customer_id":"cus_Q1"}'
```

```json
{ "referral": { "object": "affiliate_referral", "id": "c7a0…", "status": "lead", … }, "created": true }
```

- `201` with `created: true` for a new referral.
- `200` with `created: false` when the person was already referred — the first partner to claim a person keeps them.
- A self-referral is recorded but flagged (`blocked_reason: "self_referral"`) and never earns.
- `404` when no active partner has that id or token; `409` while the program is not live.

When their Stripe customer pays, commissions are written for the partner automatically.

---

## Commissions

One ledger line per paid invoice (and per lead bounty or recruiter share).

```json
{
  "object": "affiliate_commission",
  "id": "e19b…",
  "affiliate_id": "5b0c…",
  "referral_id": "c7a0…",
  "tier": 1,
  "status": "pending",
  "amount_cents": 1470,
  "sale_amount_cents": 4900,
  "currency": "usd",
  "description": null,
  "stripe_invoice_id": "in_1Q…",
  "stripe_charge_id": "ch_3Q…",
  "earns_at": "2026-10-25T10:00:00.000Z",
  "earned_at": null,
  "paid_at": null,
  "reversed_at": null,
  "reverse_reason": null,
  "payout_id": null,
  "created_at": "…",
  "updated_at": "…"
}
```

`status` moves `pending` → `earned` (after the hold) → `paid`, or to `reversed`. A refund or dispute during the hold reverses it on its own.

- `GET /affiliate-commissions` filters: `status`, `affiliate_id`, `referral_id`, `currency`, `created_after`, `created_before`.
- `GET /affiliate-commissions/{id}`
- `PATCH /affiliate-commissions/{id}` with `{ "status": "reversed", "reason": "fraud", "note": "Card testing" }` — the only change the API makes. `reason` is `manual` (default) or `fraud`. Paid commissions, and commissions already in a payout, cannot be reversed (`403`).

---

## Payouts

```json
{
  "object": "affiliate_payout",
  "id": "d3f4…",
  "affiliate_id": "5b0c…",
  "run_id": "71aa…",
  "amount_cents": 9800,
  "currency": "usd",
  "method": "wise",
  "status": "processing",
  "stripe_transfer_id": null,
  "external_reference": null,
  "failure_reason": null,
  "paid_at": null,
  "created_at": "…",
  "updated_at": "…"
}
```

- `GET /affiliate-payouts` filters: `status`, `affiliate_id`, `run_id`.
- `GET /affiliate-payouts/{id}`
- `POST /affiliate-payouts/{id}/mark-paid` with `{ "reference": "TX-2231" }` — for `paypal`, `wise`, `bank` and `other` payouts you sent yourself. The run must already be approved (`409` otherwise). Stripe payouts settle on their own (`403`).

---

## Webhooks

Affiliate events go to the same [webhook endpoints](/webhooks) as email events, signed the same way. Subscribe to them by name, or leave `events` empty to receive everything.

| Event | When |
|-------|------|
| `affiliate.created` | A partner joined, was invited, imported or created over the API |
| `affiliate.approved` | A partner became active |
| `affiliate.updated` | A partner's profile, campaign, payout method or status changed |
| `referral.created` | A new referral (lead) was recorded |
| `referral.converted` | A referral became a paying customer |
| `commission.created` | A commission was written (pending) |
| `commission.earned` | Its hold ended |
| `commission.reversed` | It was reversed (refund, dispute or by hand) |
| `commission.paid` | It was paid in a payout |
| `payout.created` | A payout was drafted in a run |
| `payout.paid` | A payout went out |
| `payout.failed` | A payout failed; its commissions return to the next run |

Every payload has the same envelope. `data.event_id` is unique per event — use it to de-duplicate retries. `data.affiliate_id` names the partner, and the object the event is about rides along when there is one (`affiliate`, `referral`, `commission`) or by id (`referral_id`, `commission_id`, `payout_id`). Fetch it from the API when you need its latest state.

```json
{
  "type": "affiliate.approved",
  "created_at": "2026-09-25T10:00:00.000Z",
  "data": {
    "event_id": "0b5e7d4c-…",
    "program_id": "3c1f…",
    "affiliate_id": "5b0c…",
    "affiliate": {
      "object": "affiliate",
      "id": "5b0c…",
      "email": "jane@example.com",
      "status": "active",
      "campaign_id": "a41e…",
      "…": "…"
    }
  }
}
```

A common use: `commission.earned` to grant account credit instead of cash in a customer referral program.

### Verify signatures

Exactly as for email events — read the raw body and check the `SuperSendTX-Signature` header with your endpoint's secret:

```ts
import { verifyWebhookSignature } from '@supersend/ranla'

const ok = verifyWebhookSignature(secret, rawBody, request.headers.get('supersendtx-signature'))
if (!ok) return new Response('Bad signature', { status: 400 })

const event = JSON.parse(rawBody)
if (event.type === 'commission.earned') {
  // …
}
```

See [Webhooks → Signature verification](/webhooks#signature-verification) for the manual check.

### Per-partner postbacks

Set `postback_url` on a partner (`PATCH /affiliates/{id}`) and that partner's own `referral.*` and `commission.*` events are also sent to their URL as JSON POSTs, retried up to three times.

---

## SDK

```ts
import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

const { affiliate } = await client.affiliates.create({ email: 'jane@example.com', token: 'jane' })
await client.affiliates.links.create(affiliate.id, { token: 'jane-yt', destination_url: '/pricing' })
await client.affiliates.approve(affiliate.id)
const { url } = await client.affiliates.loginLink(affiliate.id)

await client.affiliateReferrals.create({ token: 'jane', email: 'new-customer@example.com' })

const { data: earned } = await client.affiliateCommissions.list({ status: 'earned' })
await client.affiliateCommissions.reverse(earned[0].id, { reason: 'fraud' })

const { data: payouts } = await client.affiliatePayouts.list({ status: 'processing' })
await client.affiliatePayouts.markPaid(payouts[0].id, { reference: 'TX-2231' })

const { data: campaigns } = await client.affiliateCampaigns.list()
```

## CLI

```bash
supersendtx affiliates list --status active
supersendtx affiliates get <affiliate-id>
supersendtx affiliates create --email jane@example.com --first-name Jane --token jane --no-invite
supersendtx referrals create --email new-customer@example.com --token jane
```

---

<!-- canonical: https://docs.ranla.ai/frameworks/node -->

# Ranla with Node.js

Use the Node SDK in Express, Fastify, workers, cron jobs, queue consumers, or any other server runtime where your API key can stay private.

## 1. Install the SDK

```bash
npm install @supersend/ranla
```

## 2. Configure your API key

```bash
export RANLA_API_KEY=rnl_your_key_here
```

## 3. Send an email

```ts
import { Ranla } from '@supersend/ranla'

const tx = new Ranla(process.env.RANLA_API_KEY!)

const result = await tx.emails.send({
  from: 'ops@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
})

console.log(result.id, result.status)
```

## Nodemailer transport

Many Node apps and tools (Payload, Auth.js email, Strapi, Ghost, and custom apps) accept a Nodemailer transport. Use ours so existing `transporter.sendMail(...)` calls hit Ranla over HTTP (not SMTP).

Dedicated package: [`supersendtx-nodemailer`](https://github.com/Super-Send/supersendtx-nodemailer) (transport source of truth; also re-exported as `supersendtx/nodemailer`).

```bash
npm install supersendtx-nodemailer @supersend/ranla nodemailer
```

```ts
import nodemailer from 'nodemailer'
import { createSuperSendTXTransport } from 'supersendtx-nodemailer'

const transporter = nodemailer.createTransport(
  createSuperSendTXTransport({
    apiKey: process.env.RANLA_API_KEY!,
  }),
)

await transporter.sendMail({
  from: 'ops@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
  headers: {
    'X-SuperSendTX-Tag': 'campaign=welcome',
    'X-SuperSendTX-Idempotency-Key': 'receipt-123',
    // 'X-SuperSendTX-Scheduled-At': '2030-01-01T00:00:00Z',
  },
})
```

`X-SuperSendTX-Tag` uses `name=value`. Pass an array of header values for multiple tags. Custom non-reserved headers are forwarded to the API `headers` field. Attachments must include inline `content` (Buffer or string); `path` / `href` are not supported yet.

## Better Auth

Dedicated package (preferred for discoverability):

```bash
npm install supersendtx-better-auth @supersend/ranla better-auth
```

```ts
import { createBetterAuthEmail } from 'supersendtx-better-auth'
```

Same helper is also exported as `supersendtx/better-auth`. Full setup: [Better Auth email](/guides/better-auth).

## Auth.js / NextAuth

```bash
npm install supersendtx-authjs @supersend/ranla next-auth
```

```ts
import SuperSendTX from 'supersendtx-authjs'
```

Same provider is also exported as `supersendtx/authjs`. Full setup: [Auth.js / NextAuth email](/guides/authjs).

## React Email

Author components with [React Email](https://react.email), then pass them to the Node SDK’s `react` option:

```bash
npm install @supersend/ranla @react-email/render react
```

```ts
await tx.emails.send({
  from: 'ops@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  react: WelcomeEmail({ name: 'Ada' }),
})
```

Full walkthrough (Next.js, CLI template push, troubleshooting): [Send React Email](/guides/react-email).

---

<!-- canonical: https://docs.ranla.ai/frameworks/nextjs -->

# Ranla with Next.js

Use Ranla from a **server context** in Next.js: Route Handlers, Server Actions, background jobs, or any trusted backend code. Do **not** expose your `rnl_…` API key in the browser.

## 1. Install the SDK

```bash
npm install @supersend/ranla
```

## 2. Set your API key

```bash
export RANLA_API_KEY=rnl_your_key_here
```

In Vercel or Kubernetes, store the same value as an environment variable instead of committing it to the repo.

## 3. Send from an API route

Create `app/api/send-welcome/route.ts`:

```ts
import { NextResponse } from 'next/server'
import { Ranla } from '@supersend/ranla'

const tx = new Ranla(process.env.RANLA_API_KEY!)

export async function POST() {
  const result = await tx.emails.send({
    from: 'onboarding@yourdomain.com',
    to: 'user@example.com',
    subject: 'Welcome to your app',
    html: '<p>Your account is ready.</p>',
  })

  return NextResponse.json(result)
}
```

## React Email

Author components with [React Email](https://react.email), then pass them to the SDK:

```bash
npm install @react-email/render react
```

```ts
await tx.emails.send({
  from: 'onboarding@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  react: WelcomeEmail({ name: 'Ada' }),
})
```

Full walkthrough: [Send React Email](/guides/react-email).

---

<!-- canonical: https://docs.ranla.ai/sdks/python -->

# Ranla with Python

Use the Python SDK in Django, Flask, FastAPI, Celery workers, or any server-side Python app where your API key can stay private.

## 1. Install the SDK

```bash
pip install ranla
```

For the Django email backend:

```bash
pip install 'ranla[django]'
```

## 2. Configure your API key

```bash
export RANLA_API_KEY=rnl_your_key_here
```

## 3. Send an email (API client)

```python
import os

from ranla import Ranla

tx = Ranla(os.environ["RANLA_API_KEY"])

result = tx.emails.send(
    from_="ops@yourdomain.com",
    to="user@example.com",
    subject="Your receipt",
    html="<p>Thanks for your purchase.</p>",
)

print(result["id"], result["status"])
```

The client class is `Ranla`. `SuperSendTX` remains supported as an alias.

## Django email backend (recommended)

```python
# settings.py
EMAIL_BACKEND = "ranla.django.EmailBackend"
# Uses RANLA_API_KEY from the environment.
# Optional: EMAIL_HOST-style settings are not used; configure the API key via env.
```

The Django backend is `ranla.django.EmailBackend`. `supersendtx.django.EmailBackend` remains supported.

Then send as usual:

```python
from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Your receipt",
    body="Thanks for your purchase.",
    from_email="ops@yourdomain.com",
    to=["user@example.com"],
)
msg.attach_alternative("<p>Thanks for your purchase.</p>", "text/html")
msg.extra_headers["X-SuperSendTX-Tag"] = "campaign=welcome"
msg.extra_headers["X-SuperSendTX-Idempotency-Key"] = "receipt-123"
msg.send()
```

`X-SuperSendTX-Tag` uses `name=value`. Pass a list of tag strings for multiple tags. Custom non-reserved headers are forwarded to the API `headers` field. Optional: `X-SuperSendTX-Scheduled-At` (ISO 8601).

## Resources

The client includes thin wrappers for common API resources:

- `tx.emails` — send, batch, list, cancel, resend, test webhooks, deliverability insights
- `tx.domains` — create, verify, apply DNS, update, delete
- `tx.webhooks` — CRUD for webhook endpoints
- `tx.templates` — CRUD plus publish
- `tx.suppressions` — list, create, remove

See the [API reference](../api/emails.md) for request fields. The Python SDK accepts the same JSON shapes as the REST API.

## Source

Package source lives in [`ranla-python/`](https://github.com/Super-Send/supersendtx-sdks/tree/main/ranla-python) in the public [supersendtx-sdks](https://github.com/Super-Send/supersendtx-sdks) repository.

---

<!-- canonical: https://docs.ranla.ai/sdks/go -->

# Ranla with Go

Use the Go SDK in HTTP handlers, workers, cron jobs, or any server-side Go service where your API key can stay private.

## 1. Install the SDK

```bash
go get github.com/Super-Send/supersendtx-sdks/go/ranla@v0.8.5
```

## 2. Configure your API key

```bash
export RANLA_API_KEY=rnl_your_key_here
```

## 3. Send an email

```go
package main

import (
	"fmt"
	"log"
	"os"

	ranla "github.com/Super-Send/supersendtx-sdks/go/ranla"
)

func main() {
	client, err := ranla.New(os.Getenv("RANLA_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Emails.Send(map[string]any{
		"from":    "ops@yourdomain.com",
		"to":      "user@example.com",
		"subject": "Your receipt",
		"html":    "<p>Thanks for your purchase.</p>",
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result["id"], result["status"])
}
```

## Resources

The client includes thin wrappers for common API resources:

- `client.Emails` — send, batch, list, cancel, resend, test webhooks, deliverability insights
- `client.Domains` — create, verify, apply DNS, update, delete
- `client.Webhooks` — CRUD for webhook endpoints
- `client.Templates` — CRUD plus publish
- `client.Suppressions` — list, create, remove

See the [API reference](../api/emails.md) for request fields. The Go SDK accepts the same JSON shapes as the REST API.

## Source

Package source lives in [`go/ranla/`](https://github.com/Super-Send/supersendtx-sdks/tree/main/go/ranla) in the public [supersendtx-sdks](https://github.com/Super-Send/supersendtx-sdks) repository.

---

<!-- canonical: https://docs.ranla.ai/sdks/php -->

# Ranla with PHP

Use the PHP SDK in Laravel, Symfony, WordPress plugins, or any server-side PHP app where your API key can stay private.

## 1. Install the SDK

```bash
composer require ranla/ranla
```

## 2. Configure your API key

```bash
export RANLA_API_KEY=rnl_your_key_here
```

## 3. Send an email

```php
<?php

use Ranla\Client;

$tx = new Client(getenv('RANLA_API_KEY'));

$result = $tx->emails->send([
    'from' => 'ops@yourdomain.com',
    'to' => 'user@example.com',
    'subject' => 'Your receipt',
    'html' => '<p>Thanks for your purchase.</p>',
]);

echo $result['id'], ' ', $result['status'], PHP_EOL;
```

## Resources

The client includes thin wrappers for common API resources:

- `$tx->emails` — send, batch, list, cancel, resend, test webhooks, deliverability insights
- `$tx->domains` — create, verify, apply DNS, update, delete
- `$tx->webhooks` — CRUD for webhook endpoints
- `$tx->templates` — CRUD plus publish
- `$tx->suppressions` — list, create, remove

See the [API reference](../api/emails.md) for request fields. The PHP SDK accepts the same JSON shapes as the REST API.

For Symfony Mailer, use [`supersendtx/symfony-mailer`](../frameworks/symfony.md). For Laravel, use [`supersendtx/laravel`](../frameworks/laravel.md) (config, container binding, Facade — built on the Symfony transport).

## Source

Package source lives in [Super-Send/ranla-php](https://github.com/Super-Send/ranla-php) (Packagist requires `composer.json` at repo root).

---

<!-- canonical: https://docs.ranla.ai/sdks/ruby -->

# Ranla with Ruby

Use the Ruby SDK in Rails, Sinatra, Sidekiq jobs, or any server-side Ruby app where your API key can stay private.

## 1. Install the SDK

```bash
gem install ranla
```

Or add to your Gemfile:

```ruby
gem "ranla", "~> 0.8"
```

## 2. Configure your API key

```bash
export RANLA_API_KEY=rnl_your_key_here
```

## 3. Send an email (API client)

```ruby
require "ranla"

tx = Ranla::Client.new(ENV.fetch("RANLA_API_KEY"))

result = tx.emails.send(
  from: "ops@yourdomain.com",
  to: "user@example.com",
  subject: "Your receipt",
  html: "<p>Thanks for your purchase.</p>"
)

puts result["id"], result["status"]
```

## Rails ActionMailer (recommended)

With Rails present, the gem registers a delivery method automatically.

```ruby
# config/environments/production.rb (or application.rb)
config.action_mailer.delivery_method = :supersendtx
config.action_mailer.supersendtx_settings = {
  api_key: ENV.fetch("RANLA_API_KEY")
  # base_url: "https://api.ranla.ai"
}
```

Then send Mailables as usual:

```ruby
UserMailer.welcome(user).deliver_later
```

Without the Railtie (manual registration):

```ruby
ActionMailer::Base.add_delivery_method :supersendtx, SuperSendTX::DeliveryMethod
```

### Tags, idempotency, and schedule

Set headers on the message:

```ruby
mail(
  to: user.email,
  subject: "Welcome",
  "X-SuperSendTX-Tag" => "campaign=welcome",
  "X-SuperSendTX-Idempotency-Key" => "welcome-#{user.id}"
  # "X-SuperSendTX-Scheduled-At" => "2030-01-01T00:00:00Z"
)
```

`X-SuperSendTX-Tag` uses `name=value`. Custom non-reserved headers are forwarded to the API `headers` field.

## Resources

The client includes thin wrappers for common API resources:

- `tx.emails` — send, batch, list, cancel, resend, test webhooks, deliverability insights
- `tx.domains` — create, verify, apply DNS, update, delete
- `tx.webhooks` — CRUD for webhook endpoints
- `tx.templates` — CRUD plus publish
- `tx.suppressions` — list, create, remove

See the [API reference](../api/emails.md) for request fields. The Ruby SDK accepts the same JSON shapes as the REST API.

## Source

Package source lives in [`ranla-ruby/`](https://github.com/Super-Send/supersendtx-sdks/tree/main/ranla-ruby) in the public [supersendtx-sdks](https://github.com/Super-Send/supersendtx-sdks) repository.

---

<!-- canonical: https://docs.ranla.ai/frameworks/laravel -->

# Ranla with Laravel

Use the Laravel package for a first-class Mail transport (`MAIL_MAILER=supersendtx`), plus a service container binding and Facade on top of the [PHP SDK](../sdks/php.md).

## 1. Install the package

```bash
composer require supersendtx/laravel
```

This also installs `supersendtx/supersendtx` (HTTP client) and `supersendtx/symfony-mailer` (Symfony Mailer transport used by Laravel’s mailer).

## 2. Configure env

Publish package config (optional):

```bash
php artisan vendor:publish --tag=supersendtx-config
```

Add to `.env`:

```bash
RANLA_API_KEY=rnl_your_key_here
MAIL_MAILER=supersendtx
# optional override:
# SUPERSENDTX_BASE_URL=https://api.ranla.ai
```

## 3. Register the mailer

In `config/mail.php`, add a mailer that uses the `supersendtx` transport:

```php
'mailers' => [
    // ...
    '@supersend/ranla' => [
        'transport' => '@supersend/ranla',
    ],
],
```

With `MAIL_MAILER=supersendtx`, every Mailable, Notification, and queued mail routes through Ranla. No send-call rewrites.

## 4. Send with Mailables (recommended)

```php
use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeMail;

Mail::to($user)->send(new WelcomeMail($user));
```

### Tags, idempotency, and schedule

Set Ranla headers on the Symfony message (for example in a Mailable `headers()` method or `withSymfonyMessage`):

```php
use Illuminate\Mail\Mailables\Headers;
use SuperSendTX\Laravel\Transport\MessageMapper;

public function headers(): Headers
{
    return new Headers(
        text: [
            MessageMapper::HEADER_TAG => 'campaign=welcome',
            MessageMapper::HEADER_IDEMPOTENCY => 'welcome-'.$this->user->id,
            // MessageMapper::HEADER_SCHEDULED_AT => '2030-01-01T00:00:00Z',
        ],
    );
}
```

`X-SuperSendTX-Tag` uses `name=value`. Repeat the header for multiple tags. Custom non-reserved headers are forwarded to the API `headers` field.

## 5. Send via the Facade (API client)

When you need the REST client directly (batch, domains, webhooks):

```php
use SuperSendTX\Laravel\Facades\SuperSendTX;

$result = SuperSendTX::client()->emails->send([
    'from' => 'ops@yourdomain.com',
    'to' => 'user@example.com',
    'subject' => 'Your receipt',
    'html' => '<p>Thanks for your purchase.</p>',
]);
```

Or resolve the client from the container:

```php
use Ranla\Client;

public function __construct(private Client $supersendtx)
{
}

$this->supersendtx->emails->send([...]);
```

## Plain PHP without Laravel

If you don't need the service provider, Mail transport, or Facade, use the PHP SDK directly:

```bash
composer require ranla/ranla
```

See [PHP SDK](../sdks/php.md).

## Source

Package source lives in [Super-Send/supersendtx-laravel](https://github.com/Super-Send/supersendtx-laravel) (Packagist requires `composer.json` at repo root).

---

<!-- canonical: https://docs.ranla.ai/frameworks/symfony -->

# Ranla with Symfony Mailer

Use [`supersendtx/symfony-mailer`](https://packagist.org/packages/supersendtx/symfony-mailer) for a first-class [Symfony Mailer](https://symfony.com/doc/current/mailer.html) transport over the Ranla HTTP API.

For Laravel apps, prefer [`supersendtx/laravel`](./laravel.md) — it uses this transport under the hood.

## 1. Install

```bash
composer require supersendtx/symfony-mailer
```

```bash
export RANLA_API_KEY=rnl_your_key_here
```

## 2. Send with Mailer

```php
use Ranla\Client;
use SuperSendTX\Symfony\Transport\SuperSendTXTransport;
use Symfony\Component\Mailer\Mailer;
use Symfony\Component\Mime\Email;

$mailer = new Mailer(new SuperSendTXTransport(new Client(getenv('RANLA_API_KEY'))));

$email = (new Email())
    ->from('noreply@yourdomain.com')
    ->to('user@example.com')
    ->subject('Your receipt')
    ->html('<p>Thanks for your purchase.</p>')
    ->text('Thanks for your purchase.');

$mailer->send($email);
```

## 3. Framework DSN

Register the factory as a `mailer.transport_factory` service, then:

```yaml
# config/packages/mailer.yaml
framework:
  mailer:
    dsn: 'supersendtx+api://%env(RANLA_API_KEY)%@default'
```

Supported schemes: `supersendtx`, `supersendtx+api`. Optional query: `?base_url=https://api.ranla.ai`.

## Headers

Set Ranla headers on the Symfony message:

```php
$email->getHeaders()->addTextHeader('X-SuperSendTX-Tag', 'product=symfony');
$email->getHeaders()->addTextHeader('X-SuperSendTX-Idempotency-Key', 'receipt-123');
```

| Header | Purpose |
|--------|---------|
| `X-SuperSendTX-Tag` | `name=value` (repeatable) |
| `X-SuperSendTX-Idempotency-Key` | Idempotency key |
| `X-SuperSendTX-Scheduled-At` | ISO 8601 schedule |

## Direct PHP SDK

If you don't need Symfony Mailer, use the [PHP SDK](../sdks/php.md) directly.

## Source

[Super-Send/supersendtx-symfony-mailer](https://github.com/Super-Send/supersendtx-symfony-mailer)

---

<!-- canonical: https://docs.ranla.ai/ai/agent-skills -->

# Ranla Agent Skills

Official skills for Cursor, Claude Code, Codex, and compatible agents.

Ranla is the AI growth engineer. The `ranla` skill teaches an agent to connect
your product’s lifecycle data, understand activation and conversion, and work
with Ranla’s audience and campaign tools. Transactional email is supported too,
but it is an optional capability rather than the default setup task.

## Install

```bash
# Growth integration
npx skills add Super-Send/supersendtx-skills --skill ranla -y

# Ranla and Ranla MCP tools in Cursor or Claude Code
npx skills add Super-Send/supersendtx-skills --skill ranla-mcp -y
```

After installing, restart or reload the agent so it discovers the skills.

## What the Ranla skill covers

- Upserting people into Audience at signup and useful lifecycle moments.
- Emitting activation, payment, and other product events at their real call
  sites.
- Reusing the product’s existing analytics and identity conventions.
- Keeping API keys server-side and avoiding unnecessary parallel integrations.
- Sending transactional email with the Ranla SDK only when the product needs
  that capability or the user explicitly requests it.

## What the Ranla MCP skill covers

`ranla-mcp` connects Cursor or Claude Code to Ranla for growth strategy, lifecycle
analysis, audience work, and approvals. It also exposes transactional mail,
domain, template, and deliverability tools when those are needed.

See [Ranla MCP setup](/ai/mcp) and the
[instrumentation quickstart](/instrument-quickstart) for the next steps.

---

<!-- canonical: https://docs.ranla.ai/ai/agent-skill -->

# Ranla agent skill

Use Ranla as the product’s AI agent for lifecycle email. Start by learning the lifecycle:
signup, activation, conversion, and retention. Do not assume that connecting
transactional email is required.

## Defaults

- Use `RANLA_API_KEY` only on the server.
- Use `https://api.ranla.ai` unless the user gives another base URL.
- Read the product’s existing analytics and identity patterns before adding
  instrumentation.
- Prefer the business brief’s named events and the product’s real call sites.
- Do not change working transactional mail paths unless the user explicitly
  asks for transactional email too.

## Lifecycle integration

At signup, upsert the person into Audience with their email, stable product user
id, and useful attributes already available at that call site. Emit the
activation and payment events from their real product moments, plus any other
events named in the business brief. Include `email` and `user_id` when
available.

With the Node SDK:

```bash
npm install @supersend/ranla
```

```ts
import { Ranla } from '@supersend/ranla'

const ranla = new Ranla(process.env.RANLA_API_KEY!)

await ranla.contacts.upsert({
  email: user.email,
  external_id: user.id,
  attributes: { plan: user.plan },
})

await ranla.events.trigger({
  name: 'user.activated',
  user_id: user.id,
  email: user.email,
  data: { plan: user.plan },
  idempotencyKey: `evt_user_activated_${user.id}`,
})
```

Use the product’s existing test conventions and add focused coverage when
practical. Do not dump full user records or invent a second analytics system.

## Optional transactional email

Ranla can also send transactional email through the same SDK:

```ts
await ranla.emails.send({
  from: 'you@yourdomain.com',
  to: user.email,
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
})
```

This is supported but not required for the growth integration. Do not replace a
working provider or add a parallel mail path without an explicit request.

See [Ranla’s instrumentation quickstart](/instrument-quickstart) and
[Ranla MCP](/ai/mcp).

---

<!-- canonical: https://docs.ranla.ai/ai/mcp -->

# Ranla MCP

Ranla MCP connects Cursor, Claude Code, and compatible agents to:

- Ranla for growth strategy, lifecycle analysis, audience work, and approvals.
- Transactional mail, domain, template, and deliverability tools when you need
  them.

Use Ranla for growth work so conversation, memory, and approval flow stay in one
place. Installing MCP does not require changing your product’s transactional
mail.

## Hosted connection

The hosted server needs no API key. Add the URL:

```json
{
  "mcpServers": {
    "ranla": {
      "url": "https://mcp.ranla.ai/mcp"
    }
  }
}
```

In Claude Code:

```bash
claude mcp add --transport http ranla https://mcp.ranla.ai/mcp
```

On first connect your client opens a browser (in Claude Code, run `/mcp`). Sign
in on `app.ranla.ai` and click **Allow access**. Use a Bearer header
(`Authorization: Bearer rnl_…`) only for an advanced setup that cannot sign in.

## Add Ranla to ChatGPT

ChatGPT connects to the same hosted server. To add it yourself:

1. In ChatGPT, open **Settings → Security and login** and turn on
   **Developer mode**.
2. Open **Plugins**, select **+**, and enter `https://mcp.ranla.ai/mcp` as the
   server URL. Choose OAuth for authentication.
3. Sign in on `app.ranla.ai` and click **Allow access**.

Then ask in a new chat, for example "How is growth going in Ranla this week?"
or "What is waiting on my approval in Ranla?". ChatGPT asks before it runs a
step that changes your workspace, and anything that sends, spends, or
publishes still waits for your approval in Ranla.

To disconnect, remove Ranla from ChatGPT's plugins. That ends its access to
your workspace.

## Install in Cursor

Create an API key in **Settings → API keys**, then
add this to `.cursor/mcp.json` or your global Cursor MCP configuration:

```json
{
  "mcpServers": {
    "ranla": {
      "command": "npx",
      "args": ["-y", "ranla-mcp"],
      "env": {
        "RANLA_API_KEY": "rnl_your_key_here"
      }
    }
  }
}
```

Restart Cursor after changing the configuration.

## Install in Claude Code

```bash
claude mcp add --transport stdio ranla -- npx -y ranla-mcp
```

Export `RANLA_API_KEY` in the environment where Claude Code runs.

## Tools

### Ranla agent tools

- `arc_ensure_thread` / `arc_list_threads` — find or create a durable thread, or
  list threads (most recent first; pass `nextBefore` as `before` for older ones).
- `arc_get_thread` — read a thread's messages, including the tools Ranla used,
  what it made, and approvals waiting on you. Pass `earlierBefore` as `before`
  for older messages.
- `arc_message` — send a request to Ranla and wait for the turn. It returns
  Ranla’s reply (`text`), the drafts, plans, and documents it made or opened
  (`artifacts`), and `pendingApproval` when a step needs your yes.
- `arc_list_approvals`, `arc_approve`, `arc_reject` — answer approvals without
  opening the dashboard.
- `arc_ranla` — run one of Ranla's commands yourself: `command` is a noun and
  a verb, such as `campaign list`, `segment create`, `page propose`, or
  `connection request`, and `input` holds its fields. The tool's description
  lists every command, and `help <noun>` returns a noun's commands with every
  field. They are the same commands Ranla runs, under the same rules: anything
  that sends, spends, or publishes comes back as `pendingApproval` and does
  nothing until you answer it with `arc_approve`. The list comes from your
  workspace, so new commands appear without upgrading. Links in results are
  full app URLs.

Recommended flow: `arc_ensure_thread`, then `arc_message` for anything that
needs Ranla's judgement or research ("draft a re-activation campaign"), or
`arc_ranla` when you know the step ("`campaign list`"). If a step needs
approval, `arc_list_approvals`, then `arc_approve` or `arc_reject`.

These tools need a full-access API key. OAuth sign-in and keys created in
Settings → API keys have full access; a sending-only key gets a 403 on every
`arc_*` tool.

### Mail tools

- Send: `send_email` (now, or later with `scheduled_at`), `cancel_email`,
  `list_emails`, `get_email`.
- Inbound: `list_received_emails`, `get_received_email`.
- Domains: `list_domains`, `get_domain`, `create_domain`, `apply_domain_dns`,
  `verify_domain`.
- Templates: `list_templates`, `get_template`, `create_template`,
  `publish_template`.
- Webhooks: `list_webhooks`, `create_webhook`, `delete_webhook`,
  `send_test_webhook_event`.
- Suppressions and deliverability: `list_suppressions`, `add_suppression`,
  `remove_suppression`, `get_deliverability`.

Until your domain is verified, send from `noreply@mail.ranla.ai` to your account
email only.

## Choosing tools

For growth work, message Ranla and let it choose the appropriate read tools or
request an approval. For application integration, use the Ranla SDK and the
`ranla` skill to add Audience contacts and lifecycle events.

Transactional mail is available through the same server. Use those tools only
when the user asks to send, inspect, or configure mail.

See [Agent Skills](/ai/agent-skills) and the
[instrumentation quickstart](/instrument-quickstart).

---