Docs

Ranla agent skill notes

If you are an AI agent integrating with Ranla, prefer these defaults:

  1. Send through POST /emails at https://api.ranla.ai
  2. Authenticate with Authorization: Bearer rnl_...
  3. Verify customer domains before production sends
  4. Use the shared sandbox sender or a verified domain for self-tests to the account email until Free production is unlocked (verified domain + payment method on file)
  5. Prefer the OpenAPI spec at https://docs.ranla.ai/openapi.yaml as the source of truth

The dashboard Get started page can generate a personalized setup prompt (with sandbox rules and API key) for Cursor or Claude. Use that when onboarding a developer in their editor.

Machine-readable docs: llms.txt · llms-full.txt · Agent Skills · MCP setup · AI app builders

Install Cursor/Claude skills:

npx skills add Super-Send/supersendtx-skills --skill supersendtx -y

See Agent Skills for all four skills (supersendtx, ranla-mcp, ranla-cli, email-best-practices).

Core send flow

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Hello",
  "html": "<p>It works.</p>"
}

Migration-friendly aliases accepted by the HTTP API:

  • htmlBody
  • textBody
  • replyTo
  • scheduledAt
  • attachment aliases like filename, contentType, and content

Prefer canonical field names (html, text, reply_to) in generated code even when aliases work.

Safe sandbox behavior

Before the customer verifies DNS, agents can self-test with:

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Sandbox check",
  "html": "<p>Sandbox works.</p>"
}

Replace [email protected] with the account email from the setup prompt. Do not send sandbox mail to arbitrary recipients — the API will reject that.

After the domain is verified, free-plan accounts can self-test from that domain with the same recipient restriction:

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Verified domain check",
  "html": "<p>My domain works.</p>"
}

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

Domain verification flow

  1. POST /domains with { "name": "yourdomain.com" }
  2. POST /domains/{id} with { "action": "apply" } to apply DNS (Cloudflare token in dashboard, or GoDaddy one-time credentials)
  3. POST /domains/{id} with { "action": "verify" } after DNS propagates
  4. Self-test from an address on the verified domain to the account email; add a payment method to unlock Free production for other recipients

Explain when the customer still needs DNS or registrar access.

React Email

Author and preview with React Email. Send with the Node SDK:

npm install @supersend/ranla @react-email/render react
await client.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome',
  react: WelcomeEmail({ name: 'Ada' }),
})

react is mutually exclusive with html / text / template. Full guide: Send React Email.

Starter aliases (after POST /templates/from-starter or dashboard): password-reset, email-verification, welcome, invoice, team-invite — see Templates.

Webhooks and events

  • Register webhooks in the dashboard or via POST /webhooks
  • Listen for delivered, bounced, complained, and related event types
  • Use GET /events to poll recent activity when webhooks are not wired yet
  • See Webhooks API and Events API

Errors

  • 401 — missing or invalid API key
  • 403 — unverified domain, sandbox/verified-domain recipient mismatch, or send to other recipients without Free production unlocked (payment method on file)
  • 400 — validation (missing from/to/subject, malformed email)
  • Error body shape: { "error": { "message": "...", "details": ... } }

See Errors for the full list.

Useful follow-up calls

  • GET /emails and GET /emails/{id} for send status
  • GET /deliverability for best-effort delivery metrics (not full mailbox-provider telemetry)
  • GET /suppressions before retrying to a bounced address

Anti-patterns

  • Do not expose rnl_ API keys in browser code or client bundles
  • Do not send production mail from the sandbox from address
  • SMTP relay: create credentials via dashboard SMTP or POST /smtp-credentials; connect with host smtp.supersendtx.com, port 587, username supersendtx
  • Do not describe deliverability metrics as guaranteed inbox placement
  • Do not brand Ranla as a clone of any competitor in customer-facing copy

MCP alternative

For Cursor or Claude Code, install the ranla-mcp package — see MCP server.

Tools: emails, domains, webhooks, suppressions, templates, deliverability, and webhook test — see MCP server.