SDK Reference

Install and use the @molted/mail TypeScript SDK to send email, classify intents, and coordinate agents.

The @molted/mail SDK is a TypeScript client for the Molted Email API. It wraps every agent endpoint in a typed method with built-in error handling.

Install

npm install @molted/mail

Initialize

import { MailClient } from "@molted/mail";

const client = new MailClient({
  baseUrl: "https://api.molted.email",
  apiKey: "YOUR_API_KEY",
});

Methods

`requestSend(input)`

Send an email through the policy engine.

const result = await client.requestSend({
  tenantId: "tenant_abc123",
  recipientEmail: "user@example.com",
  templateId: "welcome",
  dedupeKey: "welcome-user@example.com",
  payload: { firstName: "Alice", trialDays: 14 },
  // Optional: mailbox scoping (recommended)
  mailboxId: "mbx_abc123",
  // Optional: agent-specific fields
  sendReason: "Onboarding sequence step 1",
  idempotencyKey: "onboard-user@example.com-step1",
  // Optional: deferred send
  scheduledAt: "2026-03-24T09:00:00Z",
  // Optional: attachments (upload via POST /v1/attachments first)
  attachments: [{ id: "uuid", filename: "report.pdf", contentType: "application/pdf" }],
  // Optional: humanizer
  humanize: true,
  humanizeStyle: "professional",
});
// → { requestId: "req_abc123", status: "queued" | "blocked" | "scheduled" }

Field	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`recipientEmail`	`string`	Yes	Recipient email address.
`templateId`	`string`	Yes	Template to use.
`dedupeKey`	`string`	Yes	Unique key to prevent duplicates.
`payload`	`object`	Yes	Template variables passed to the template at render time.
`mailboxId`	`string`	No	Mailbox to send from. Scopes the send to a specific mailbox and projects it into a conversation thread. Recommended.
`sendReason`	`string`	No	Human-readable context for the decision trace.
`idempotencyKey`	`string`	No	Alias for `dedupeKey`.
`scheduledAt`	`string`	No	ISO 8601 timestamp to defer the send to a future time. Returns `status: "scheduled"`.
`attachments`	`array`	No	Attachment refs: `[{ id, filename, contentType }]`. Upload via `POST /v1/attachments` first.
`humanize`	`boolean`	No	Enable humanizer rewriting.
`humanizeStyle`	`string`	No	Style: `casual`, `professional`, or `friendly`.

`proposeEmail(input)`

Generate draft candidates with a policy pre-check and contact context.

const result = await client.proposeEmail({
  tenantId: "tenant_abc123",
  recipientEmail: "user@example.com",
  // optional: pass structured context to influence candidate selection
  context: { lastPurchaseDate: "2026-01-15" },
});
// → { draftCandidates, policyPreCheck, contactContext }

`scheduleFollowup(input)`

Schedule a follow-up email with optional trigger conditions.

const result = await client.scheduleFollowup({
  tenantId: "tenant_abc123",
  contactEmail: "user@example.com",
  threadRequestId: "req_abc123",
  delayMinutes: 1440,
  triggerConditions: { noReply: true },
  cancelOnReply: true,
});
// → { followupId, status, scheduledAt }

Field	Type	Required	Description
`tenantId`	`string`	Yes	Your tenant identifier.
`contactEmail`	`string`	Yes	Contact email address.
`threadRequestId`	`string`	Yes	Original send request to follow up on.
`delayMinutes`	`number`	One of `delayMinutes` or `scheduledAt`	Minutes to wait before sending.
`scheduledAt`	`string`	One of `delayMinutes` or `scheduledAt`	ISO 8601 timestamp for absolute scheduling.
`triggerConditions`	`object`	No	Conditions that must be met to send.
`cancelOnReply`	`boolean`	No	Cancel if the contact replies first.

`recordInbound(input)`

Record an inbound email for processing, linking, and classification.

const result = await client.recordInbound({
  tenantId: "tenant_abc123",
  fromEmail: "customer@example.com",
  toEmail: "support@yourdomain.com",
  subject: "Need help with my account",
  bodyText: "I can't log in...",
  bodyHtml: "<p>I can't log in...</p>",
  // Optional threading and provider fields
  inReplyTo: "<original-message-id@provider.com>",
  referencesHeader: "<original-message-id@provider.com>",
  providerMessageId: "provider-msg-id-123",
  mailboxId: "mailbox-uuid",
  threadId: "thread-uuid",
});
// → { messageId, linkedRequestId, classificationJobId }

`classifyIntent(input)`

Classify the intent of an inbound message.

const result = await client.classifyIntent({
  tenantId: "tenant_abc123",
  subject: "Re: Follow up",
  bodyText: "Sounds great, let's schedule a call next week.",
});
// → { intent, confidence, suggestedAction, flags, allScores, runnerUpIntent }

See Inbound Email for the full list of intent categories and suggested actions.

`nextBestAction(input)`

Get a recommendation for what to do next with a contact.

const result = await client.nextBestAction({
  tenantId: "tenant_abc123",
  contactEmail: "user@example.com",
});
// → { recommendation, reasoning, contactSummary }

Recommendations: reply, wait, nudge, stop, escalate.

`getThreadContext(input)`

Retrieve full thread context for a contact, including timeline, suppression status, and active incidents.

const result = await client.getThreadContext({
  tenantId: "tenant_abc123",
  contactEmail: "user@example.com",
});
// → { timeline, suppressionStatus, activeIncidents, lastClassification }

On this page