Hi {{name}}, thanks for signing up.
',\n bodyText: 'Hi {{name}}, thanks for signing up.',\n },\n params: { name: 'Ada' },\n recipient: { email: 'ada@example.com' },\n});\n\nconst status = await ray.sends.get(sendId);\nconsole.log(status.aggregate); // { total: 1, pending: 1 } → later { total: 1, delivered: 1 }\n```\n\n`send()` resolves as soon as Ray accepts the request (HTTP `202`). Delivery is asynchronous; read it with `ray.sends.get()` or subscribe to [delivery webhooks](#delivery-webhooks).\n\nKeep the API key on the server. Never ship it to browsers or mobile apps.\n\n## Sending\n\n`ray.send(body, options?)` calls `POST /send` and returns `{ sendId }`. A request uses exactly one of four modes, and every channel delivery uses exactly one content source: `templateId` (a published template) or inline `content`. The `SendBody` type rejects invalid combinations at compile time.\n\n### Single recipient, with a template\n\n```ts\nconst { sendId } = await ray.send(\n {\n channelConfigId: '9f1c2a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b',\n templateId: '1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a',\n params: { name: 'Ada', code: '482913' },\n recipient: { email: 'ada@example.com', name: 'Ada Lovelace' },\n externalUserId: 'user_123', // your id for the end user\n showInFeed: true, // also add an entry to user_123's in-app feed\n },\n { idempotencyKey: 'signup-code-user_123-482913' },\n);\n```\n\n### Single recipient, with inline content\n\nThe `content` shape depends on the channel's template kind (see [Channels](#channels)). Here, a push notification:\n\n```ts\nawait ray.send({\n channelConfigId: '3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d', // fcm_push\n content: { title: 'Order shipped', body: 'Order {{orderId}} is on its way.' },\n logTitle: 'Order shipped', // feed title, inline content only\n logDescription: 'Order {{orderId}} left the warehouse.',\n params: { orderId: 'A-1042' },\n recipient: { deviceToken: 'fcm-device-token-from-your-app' },\n externalUserId: 'user_123',\n showInFeed: true,\n});\n```\n\nWith inline content every top-level `{{variable}}` in `content`, `logTitle` and `logDescription` needs a value in `params`.\n\n### Fan-out (1 to 1000 recipients)\n\n`targets[]` sends the same rendered message to many recipients on one channel in one request (one `sendId`, one rate-limit token).\n\n```ts\nconst users = [\n { id: 'user_1', email: 'ada@example.com' },\n { id: 'user_2', email: 'grace@example.com' },\n];\n\nawait ray.send({\n channelConfigId: '9f1c2a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b',\n templateId: '1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a',\n params: { releaseName: 'September update' }, // one params set for everyone\n targets: users.map((u) => ({ recipient: { email: u.email }, externalUserId: u.id })),\n showInFeed: true, // one feed entry per target with an externalUserId\n priority: 'low', // bulk: never delays transactional sends\n});\n```\n\nOne invalid target rejects the whole request with `400`. For per-recipient values (a name, a code) make one send per recipient. For more than 1000 recipients, split into several sends.\n\n### Multi-channel (one person, 1 to 10 channels)\n\n```ts\nawait ray.send({\n externalUserId: 'user_42',\n params: { feature: 'dark mode' },\n feed: { title: 'New feature is live', description: 'Try dark mode in settings.' },\n deliveries: [\n {\n channelConfigId: '3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d', // push\n content: { title: 'New: {{feature}}', body: 'Open settings to try it.' },\n recipient: { deviceToken: 'fcm-device-token-from-your-app' },\n },\n {\n channelConfigId: '9f1c2a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b', // email\n templateId: '1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a',\n recipient: { email: 'ada@example.com' },\n },\n {\n channelConfigId: '7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f', // slack\n content: { text: 'Shipped *{{feature}}* to user_42' },\n params: { feature: 'dark mode (beta)' }, // replaces top-level params for this delivery\n recipient: {},\n },\n ],\n});\n```\n\n`feed` with `deliveries` creates exactly one feed entry (requires top-level `externalUserId`). Each channel is delivered and retried independently.\n\n### Feed-only (in-app notification, no channel)\n\n```ts\nawait ray.send({\n externalUserId: 'user_42',\n feed: { title: 'Your export is ready', description: 'Download it from the Reports page.' },\n});\n```\n\n### Scheduling\n\nPass `notBefore` (ISO 8601, offsets allowed) to deliver later. Feed entries become visible at that time too.\n\n```ts\nawait ray.send({\n channelConfigId: '9f1c2a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b',\n templateId: '1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a',\n recipient: { email: 'ada@example.com' },\n notBefore: '2026-09-15T09:00:00+08:00',\n});\n```\n\n### Email attachments, cc and bcc\n\nAttachments are base64 inside the email recipient (up to 20 files, about 10 MiB each, about 25 MiB total; `POST /send` accepts bodies up to 45 MiB).\n\n```ts\nimport { readFile } from 'node:fs/promises';\n\nawait ray.send({\n channelConfigId: '9f1c2a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b',\n content: {\n subject: 'Invoice {{number}}',\n bodyHtml: 'Your invoice is attached.
Hi {{name}}
',\n bodyText: 'Hi {{name}}',\n },\n logTitle: 'Welcome email sent',\n logDescription: 'Welcomed {{name}}',\n publish: true,\n});\n\nconst { templates } = await ray.templates.list({ folder: 'onboarding', includeArchived: false });\nconst template = await ray.templates.get(id); // includes `published` and `draft` versions\n\n// Update the draft (full body; channelKind can't change), then publish it\nawait ray.templates.update(id, {\n name: 'welcome-email',\n channelKind: 'email_html',\n content: { subject: 'Welcome aboard, {{name}}', bodyHtml: 'Hi {{name}}
', bodyText: 'Hi {{name}}' },\n logTitle: 'Welcome email sent',\n logDescription: 'Welcomed {{name}}',\n});\nawait ray.templates.publish(id);\n\n// Send the published version once to yourself (no feed entry, no webhooks)\nawait ray.templates.testSend(id, {\n channelConfigId: '9f1c2a7e-3b4d-4e5f-8a6b-1c2d3e4f5a6b',\n recipient: { email: 'me@example.com' },\n params: { name: 'Test' },\n});\n\nawait ray.templates.archive(id);\nawait ray.templates.unarchive(id);\n```\n\nTemplates use `{{variable}}` placeholders and `{{#section}}...{{/section}}` blocks. See https://ray.gege.mn/docs/templates\n\n## Channels\n\n```ts\nconst { channels } = await ray.channels.list();\n// [{ id, name, kind: 'ses_email', templateKind: 'email_html', recipientSchema: { ...JSON Schema } }]\n```\n\nChannels are configured in the dashboard. `channelConfigId` in `send()` is a channel's `id`.\n\n| Channel `kind` | Template kind | `recipient` | Inline `content` |\n| --- | --- | --- | --- |\n| `ses_email`, `smtp_email` | `email_html` | `{ email, name?, cc?, bcc?, from?, replyTo?, headers?, attachments? }` | `{ subject, bodyHtml, bodyText }` |\n| `fcm_push` | `fcm_basic` | `{ deviceToken }` or `{ topic }` | `{ title, body, imageUrl?, data? }` |\n| `slack_webhook` | `slack_text` | `{}` | `{ text }` |\n| `discord_webhook` | `discord_text` | `{}` | `{ content }` |\n| `telegram_bot` | `telegram_text` | `{ chatId }` | `{ text, disableLinkPreview? }` |\n| `twilio_sms` | `sms_text` | `{ phoneNumber }` (E.164, e.g. `'+97699112233'`) | `{ text }` |\n| `sendsms_mn` | `sms_text` | `{ phoneNumber }` (Mongolian 8 digits, e.g. `'99112233'`) | `{ text }` |\n| `generic_webhook` | `webhook_json` | `{}` | `{ title, body, data? }` |\n\nSMS (`twilio_sms`, `sendsms_mn`) is plain text of up to 1600 characters; param values are inserted verbatim. On Twilio, text longer than 1600 characters after params are filled in makes `send()` / `testSend()` throw a `400`. Long messages go out as several SMS. Twilio splits them itself. sendsms.mn accepts one SMS per request, so Ray splits the message at spaces and line breaks into parts of at most 159 characters of plain Latin (GSM-7) text, or 69 once a part has any other character, such as Cyrillic; each part is sent in order, billed as one SMS and arrives as a separate message. A split message's `providerMessageId` is the comma-separated sendsms.mn ids, and it counts once toward `ratePerMinute`. sendsms.mn failures after which an SMS may already be out (a timeout, or any failure after the first part was sent) are not retried, to avoid sending it twice.\n\n```ts\nawait ray.send({\n channelConfigId: '8e9f0a1b-2c3d-4e5f-8a6b-7c8d9e0f1a2b', // twilio_sms\n content: { text: 'Your Acme code is {{code}}. It expires in 10 minutes.' },\n logTitle: 'Login code',\n logDescription: 'Login code sent by SMS',\n params: { code: '482913' },\n recipient: { phoneNumber: '+97699112233' }, // sendsms_mn: '99112233'\n});\n```\n\nFailed SMS deliveries carry `providerError.name` `TwilioError` or `SendsmsMnError` on the delivery row.\n\n## Click stats\n\n```ts\nconst stats = await ray.clicks.get({ sendId }); // or { campaignId: 'invoices-2026-09' }\nstats.totalClicks;\nstats.byUrl; // [{ url, clicks }]\n```\n\n## Delivery webhooks\n\nRay POSTs to your endpoint when a delivery reaches a final state (Pro plan and above).\n\n```ts\nconst webhook = await ray.webhooks.create({\n name: 'production',\n url: 'https://api.example.com/webhooks/ray',\n events: ['notification.failed_terminal', 'send.completed'],\n});\nconsole.log(webhook.secret); // shown only now: store it as RAY_WEBHOOK_SECRET\n\nconst { webhooks } = await ray.webhooks.list();\nconst one = await ray.webhooks.get(webhook.id); // consecutiveFailures, lastError, ...\n\nawait ray.webhooks.update(webhook.id, { events: ['send.completed'], enabled: true });\nconst { secret } = await ray.webhooks.update(webhook.id, { rotateSecret: true }); // old secret stops working\nawait ray.webhooks.delete(webhook.id); // archives it\n```\n\nEvents: `notification.delivered`, `notification.failed_terminal`, `send.completed`. Delivery is at-least-once and unordered: deduplicate on `notification_log_id` (notification events) or `send_id` (`send.completed`). Details: https://ray.gege.mn/docs/webhooks\n\n## Verifying webhooks\n\nRay signs every delivery webhook with the `X-Ray-Signature` header:\n\n```http\nX-Ray-Signature: t=1789378201,v1=5f2b7c1e9a0d4b3c8e6f1a2d7b9c0e4f3a5d8b1c6e2f9a7d0b4c3e8f1a6d2b9c\n```\n\n`v1` is the hex HMAC-SHA256 of `\"