Email (totalum-sdk/email)

import … from 'totalum-sdk/email' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Send transactional e-mail (sign-up confirmations, receipts, notifications) from the project's own sender, and check whether it was delivered. The HTML you pass is sent byte for byte. Billed in credits per recipient.

await totalum.email.send({ to: 'ana@example.com', subject: 'Welcome', html: '<p>Hi Ana</p>' });

#totalumEmail

totalumEmail(options?: TotalumClientOptions): TotalumEmail

Creates the email namespace (the same object as totalum.email, scope email): HTML sent byte for byte, charged per recipient, sent from the project's own address p-<project>@mail.totalum-project.com.

Parameters

Returns TotalumEmail — The email namespace: the methods below.

Example

import { totalumEmail } from 'totalum-sdk/email';

const email = totalumEmail();
await email.send({ to: 'ana@example.com', subject: 'Welcome', html: '<p>Hi Ana</p>' });

The namespace's type is exported as TotalumEmail (import type { TotalumEmail } from 'totalum-sdk/email').

#email.send

email.send(msg: EmailSendInput): Promise<{ id, status, message, success, messageId, usage }>

Sends one e-mail from the project's sender address: sign-up confirmations, receipts, notifications, password resets. The HTML is sent byte for byte (inline your CSS); add text for clients that show plain text. Charged per recipient (usage.credits). Keep the returned id to check delivery with get(id).

Parameters

Returns Promise<{ id, status, message, success, messageId, usage }> — The e-mail's id, its status and what it cost.

Errors — besides the errors every call can throw:

Example

const sent = await totalum.email.send({
  to: 'ana@example.com',
  subject: 'Your invoice F-2026-0012',
  html: '<p>Hi Ana,</p><p>Your invoice is attached.</p>',
  text: 'Hi Ana, your invoice is attached.',
  attachments: [{ filename: 'F-2026-0012.pdf', url: invoice.url }],
  replyTo: 'billing@acme.com',
});

Result:

{
  "success": true,
  "message": "Email sent successfully",
  "messageId": "01a12c0c-9e5f-74ea-a128-a72d3fdd47ae",
  "id": "em_01M4P0S77M6XCM69SYZWP1XME9",
  "status": "queued",
  "usage": { "credits": 0.0515 }
}

#email.get

email.get(id: string): Promise<EmailView | null>

An e-mail's delivery status and history (queued, sent, delivered, bounced, …): show it on an admin page or retry a bounced address. Free.

Parameters

Returns Promise<EmailView \| null> — The e-mail and its events, or null when it is not this project's.

Errors — besides the errors every call can throw:

Example

const view = await totalum.email.get('em_01M4P0S77M6XCM69SYZWP1XME9');

Result:

{
  "id": "em_01M4P0S77M6XCM69SYZWP1XME9",
  "from": "\"Acme\" <p-acme-crm@mail.totalum-project.com>",
  "to": ["ana@example.com"],
  "subject": "Your invoice F-2026-0012",
  "status": "delivered",
  "lastEventAt": "2026-10-11T17:39:02.000Z",
  "events": [
    { "type": "email.sent", "at": "2026-10-11T17:38:58.000Z" },
    { "type": "email.delivered", "at": "2026-10-11T17:39:02.000Z" }
  ]
}

#EmailSendInput

One e-mail, for email.send().

#EmailSendOutput

The answer of email.send().

#EmailView

An e-mail and its delivery history, from email.get().