Send

The kraiter.send namespace provides methods for sending one-off transactional emails and inspecting send history. 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',
  template: 'tmpl_welcome',
  variables: {
    firstName: 'Alice',
    activationUrl: 'https://app.example.com/activate?token=abc',
  },
});

console.log(result.messageId); // SES message ID
console.log(result.status);    // "sent"
console.log(result.sendId);    // send record ID (once written)

The method resolves only when the email was accepted for delivery. Every failure mode — validation, unverified domain, a suppressed or unsubscribed contact, a missing template — throws a MailerError instead of returning. There is no success flag to check: reaching the result means the email was sent.

Parameters

Parameter	Type	Required	Description
`to`	`string`	Yes	The recipient email address.
`template`	`string`	Yes	The ID of the template to render.
`variables`	`Record<string, unknown>`	No	Template variables to interpolate into the subject line and body.
`from`	`string`	No	Custom from address. Must use a verified sending domain.
`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<TransactionalSendResult> — information about the successful send.

TransactionalSendResult object

Field	Type	Description
`messageId`	`string`	The message ID returned by SES.
`status`	`"sent"`	Always `"sent"` on success.
`sendId`	`string`	The send record ID in Kraiter. Present once the send record has been written. Use it to look up delivery status.

Errors

Code	When
`NOT_FOUND`	The `template` 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, or the recipient is suppressed/unsubscribed.

Error handling example

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

try {
  await kraiter.send.transactional({
    to: 'alice@example.com',
    template: 'tmpl_receipt',
    variables: { orderId: '12345' },
  });
} catch (error) {
  if (error instanceof MailerError) {
    switch (error.code) {
      case 'NOT_FOUND':
        console.error('Template not found — check the template ID');
        break;
      case 'VALIDATION_ERROR':
        console.error('Invalid request:', error.message);
        break;
      case 'FORBIDDEN':
        console.error('Send rejected — domain unverified or recipient suppressed');
        break;
      default:
        console.error('Unexpected error:', error.message);
    }
  }
}

Unsubscribe behaviour

By default, the SDK respects contact suppression. If the recipient has unsubscribed or been suppressed, the send is rejected — the call throws a MailerError rather than returning a result. It is never silently dropped, so a resolved promise always means the email was sent.

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',
  template: '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',
  template: '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.

get

Retrieves a single send record by ID. Returns null if not found.

const send = await kraiter.send.get('snd_abc123');

if (send) {
  console.log(send.status, send.sentAt);
}

Parameters

Parameter	Type	Required	Description
`sendId`	`string`	Yes	The send ID.

Returns

Promise<SendHistoryEntry | null> — the send record, or null if not found.

list

Lists send history with cursor-based pagination. Optionally filter by contact, template, or sequence.

const page = await kraiter.send.list({ templateId: 'tmpl_welcome', limit: 50 });

for (const send of page.items) {
  console.log(send.toAddress, send.status, send.sentAt);
}

Parameters

Parameter	Type	Required	Description
`contactId`	`string`	No	Filter to a single contact.
`templateId`	`string`	No	Filter to a single template.
`sequenceId`	`string`	No	Filter to a single sequence.
`limit`	`number`	No	Maximum items per page.
`cursor`	`string`	No	Pagination cursor.

Returns

Promise<{ items: SendHistoryEntry[]; nextCursor?: string }> — a page of send records.

Send

On this page