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: {
    subject: "Welcome!",
    html: "<h1>Welcome aboard</h1>",
    text: "Welcome aboard",
  },
  // Optional: agent-specific fields
  agentId: "agent-1",
  sendReason: "Onboarding sequence step 1",
  idempotencyKey: "onboard-user@example.com-step1",
  // Optional: humanizer
  humanize: true,
  humanizeStyle: "professional",
});
// → { requestId: "req_abc123", status: "queued" | "blocked" }

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	Email content and template variables.
`agentId`	`string`	No	Calling agent's identifier.
`sendReason`	`string`	No	Why this email is being sent.
`idempotencyKey`	`string`	No	Idempotency key for agent sends.
`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",
  contactEmail: "user@example.com",
  templateId: "follow-up",
  payload: { subject: "Checking in", html: "...", text: "..." },
});
// → { 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`	Yes	Minutes to wait before sending.
`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>",
});
// → { messageId, linkedRequestId, classificationJobId }

`classifyIntent(input)`

Classify the intent of an inbound message.

const result = await client.classifyIntent({
  tenantId: "tenant_abc123",
  contactEmail: "customer@example.com",
  messageText: "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