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.

Marketing site, not product? That is one line of HTML and a separate install — see Track your website.

What you are setting up

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 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.
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.
2. Open Home (/overview) or Settings → API keys and click Create API key.
3. Copy the rnl_… secret once.

export RANLA_API_KEY=rnl_your_key_here

2. Install the SDK

npm install @supersend/ranla

import { Ranla } from '@supersend/ranla'

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

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

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 and agent skill notes.

3. Track product events

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

await client.events.trigger({
  name: 'user.created',
  user_id: 'user_123',
  email: '[email protected]',
  data: { plan: 'trial', source: 'signup' },
  idempotencyKey: 'evt_user_created_123',
})

Common first events:

REST equivalent:

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": "[email protected]",
    "data": { "plan": "trial" }
  }'

See Events API 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 §4 for the full DNS table.

5. Send a test email (optional but recommended)

Confirm the pipe works before you rely on automations:

curl -X POST https://api.ranla.ai/emails \
  -H "Authorization: Bearer $RANLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "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

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:

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:

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:

<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:

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 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 for user.created → welcome sequence.

Next steps

• What is Ranla
• Track your website · On-site messages
• Google Ads · Revenue
• Connect analytics · Events API
• Automations · Templates
• Quickstart: send email
• Agent skill notes · MCP server