Send

The kraiter.send namespace provides methods for sending one-off transactional emails. Use this for emails triggered by a user action — password resets, order confirmations, welcome emails, and similar.

transactional

Sends a single transactional email to one recipient using a pre-defined template.

const result = await kraiter.send.transactional({
  to: 'alice@example.com',
  templateId: 'tmpl_welcome',
  variables: {
    firstName: 'Alice',
    activationUrl: 'https://app.example.com/activate?token=abc',
  },
});

console.log(result.sendId); // unique ID for this send
console.log(result.status); // e.g. "queued"

Parameters

Parameter	Type	Required	Description
`to`	`string`	Yes	The recipient email address.
`templateId`	`string`	Yes	The ID of the template to render.
`variables`	`Record<string, unknown>`	No	Template variables to interpolate into the subject line and body.
`ignoreUnsubscribe`	`boolean`	No	When `true`, the email is sent even if the contact has unsubscribed. Use only for legally required messages such as invoices or security alerts. Defaults to `false`.

Returns

Promise<SendResult> — information about the queued send.

SendResult object

Field	Type	Description
`sendId`	`string`	A unique identifier for this send. Use it to look up delivery status.
`status`	`string`	The initial status of the send (typically `"queued"`).
`to`	`string`	The recipient email address.
`templateId`	`string`	The template that was used.

Errors

Code	When
`NOT_FOUND`	The `templateId` does not match any template.
`VALIDATION_ERROR`	The `to` address is invalid or a required template variable is missing.
`FORBIDDEN`	Your sending domain is not verified.

Error handling example

import { KraiterError } from '@kraiter/sdk';

try {
  await kraiter.send.transactional({
    to: 'alice@example.com',
    templateId: 'tmpl_receipt',
    variables: { orderId: '12345' },
  });
} catch (error) {
  if (error instanceof KraiterError) {
    switch (error.code) {
      case 'NOT_FOUND':
        console.error('Template not found — check the templateId');
        break;
      case 'VALIDATION_ERROR':
        console.error('Invalid request:', error.message);
        break;
      case 'FORBIDDEN':
        console.error('Domain not verified — complete domain setup first');
        break;
      default:
        console.error('Unexpected error:', error.message);
    }
  }
}

Unsubscribe behaviour

By default, the SDK respects contact suppression. If the recipient has unsubscribed, the send is silently skipped and the returned status will reflect this.

Set ignoreUnsubscribe: true only when the email is legally required — for example, a payment receipt or a security notification. Misusing this flag may harm your sender reputation.

// Send a legally required invoice email regardless of unsubscribe status
await kraiter.send.transactional({
  to: 'alice@example.com',
  templateId: 'tmpl_invoice',
  variables: { invoiceId: 'INV-2025-001' },
  ignoreUnsubscribe: true,
});

Template variables

Variables passed in the variables object are interpolated into the template's subject line and body using Liquid syntax. If your template references a variable that is not provided, it will render as an empty string.

// Template subject: "Your order {{ orderId }} has shipped"
// Template body contains: "Hi {{ firstName }}, ..."
await kraiter.send.transactional({
  to: 'alice@example.com',
  templateId: 'tmpl_shipping',
  variables: {
    firstName: 'Alice',
    orderId: 'ORD-9876',
    trackingUrl: 'https://track.example.com/abc',
  },
});

See the Templates guide for more on Liquid syntax and variable usage.

Send

On this page