@mindstudio-ai/agent 0.1.109 → 0.1.111

package/dist/index.d.ts

@@ -2238,6 +2238,15 @@ interface Citation {
 }
 /** A metadata value as stored on a document: scalars only. */
 type MetadataValue = string | number | boolean;
+/**
+ * Numeric range over a metadata value (inclusive both ends). Numbers only —
+ * to range on dates, store them as sortable integers at add time (epoch
+ * seconds or `20240315`-style YYYYMMDD) and range on those.
+ */
+interface MetadataRange {
+    gte?: number;
+    lte?: number;
+}
 /**
  * Tags attached to a document when it's added — department, year, doc type,
  * a per-user scope — and matched by {@link SearchFilter.metadata} at query
@@ -2261,10 +2270,11 @@ type SearchMode = 'hybrid' | 'semantic' | 'lexical';
 interface SearchFilter {
     /**
      * Match document metadata set at add time. A scalar must equal; an array
-     * matches any of its values. Keys AND together:
-     * `{ department: 'legal', year: [2025, 2026] }`.
+     * matches any of its values; `{ gte?, lte? }` matches a numeric range. Keys
+     * AND together:
+     * `{ department: 'legal', year: [2025, 2026], publishedAt: { gte: 20250101 } }`.
      */
-    metadata?: Record<string, MetadataValue | MetadataValue[]>;
+    metadata?: Record<string, MetadataValue | MetadataValue[] | MetadataRange>;
     /** Exact filename, or any of several. */
     filename?: string | string[];
     /** Restrict to specific documents (ids from {@link DataSource.documents}). */
@@ -2297,7 +2307,16 @@ interface SearchExplain {
     matchedVia: 'dense' | 'lexical' | 'both';
 }
 interface SearchHit {
-    /** Provider relevance score. Comparable within a response, not across them. */
+    /**
+     * Relevance of this hit. Comparable within a response, not across them —
+     * the scale depends on how the search ran (check {@link SearchRan}):
+     * cosine similarity in `semantic` mode, an RRF rank reciprocal in `hybrid`
+     * (small numbers that are not similarities), keyword-overlap weight in
+     * `lexical`. When reranking ran, it's the reranker's 0–1 relevance instead,
+     * with the retrieval value preserved as `retrievalScore` — so rerank-on
+     * `score` is the one scale that's stable across modes, and the right place
+     * for quality cutoffs.
+     */
     score: number;
     /** The matched chunk, prefixed with its heading path for context. */
     text: string;
@@ -2359,7 +2378,7 @@ interface SearchRan {
  * vector, so they take effect on the next call and cost nothing. Anything that
  * would require rebuilding the corpus — chunking, the embedding model, whether
  * chunks are contextualized — is a property of the data source, configured
- * with `mindstudio-prod datasources config` rather than passed here.
+ * with `remy-admin datasources config` rather than passed here.
  *
  * The defaults come from the data source's own configuration, so most callers
  * should pass nothing.
@@ -2367,7 +2386,14 @@ interface SearchRan {
 interface SearchOptions {
     /** Results to return. Default 5, capped at 50. */
     topK?: number;
-    /** Drop hits below this score. Provider-specific scale — measure before using. */
+    /**
+     * Floor on the RETRIEVAL score — applied to the retrieval branch, never to
+     * the fused hybrid score or the reranker's score. In `semantic` and
+     * `hybrid` modes it's a cosine floor on the embedding branch; in `lexical`,
+     * a keyword-overlap floor. The scale depends on the embedding model, so
+     * measure before using — and with reranking on, prefer cutting on each
+     * hit's returned `score` (the reranker's 0–1 relevance) instead.
+     */
     scoreThreshold?: number;
     /**
      * Narrow the search to matching chunks before ranking — by document
@@ -2869,12 +2895,16 @@ interface Analytics {
 }
 
 /**
- * The `email` namespace: read and manage your app's OWN outbound email.
+ * The `email` namespace: send, read and manage your app's OWN outbound email.
+ *
+ * `email.send()` is the send path. The older `mindstudio.sendEmail({...})` action
+ * still works and shares exactly the same implementation, so nothing breaks — but
+ * `send()` is the one to reach for: it returns a proper receipt (including the
+ * `batchId` you read stats back with) and it lives alongside everything you do
+ * with the result.
  *
- * Sending is not here — that's the `sendEmail` action
- * (`mindstudio.sendEmail({...})`). This namespace is everything *after* the send:
- * what happened to each message, how a campaign performed, and who has
- * unsubscribed.
+ * The rest of the namespace is everything *after* the send: what happened to each
+ * message, how a campaign performed, and who has unsubscribed.
  *
  * The point is that you can build your own email admin screen inside your own app
  * and never open the MindStudio dashboard. So this deliberately includes the
@@ -2882,7 +2912,7 @@ interface Analytics {
  * unsubscribe list, this can do too.
  *
  * Every call is scoped to the executing app by its request token; there is no
- * appId parameter and no way to read another app's mail.
+ * appId parameter and no way to read or send as another app.
  */
 /** Where a message got to. See `EmailMessage.status`. */
 type EmailMessageStatus = 
@@ -2946,6 +2976,17 @@ interface EmailStats {
         counts: Record<string, number>;
     }>;
 }
+/**
+ * Lifecycle of a QUEUED send. Large and marketing sends are accepted
+ * immediately and delivered in the background, so a blast can legitimately be
+ * observed mid-flight:
+ *
+ * `accepted` — queued, nothing delivered yet. `sending` — delivery in
+ * progress. `completed` — every recipient was handed to the provider.
+ * `partial` — finished, but some recipients were not sent to. `failed` —
+ * finished and nothing was sent.
+ */
+type EmailBatchLifecycle = 'accepted' | 'sending' | 'completed' | 'partial' | 'failed';
 /**
  * One blast, aggregated.
  *
@@ -2959,6 +3000,17 @@ interface EmailBatch {
     recipients: number;
     accepted: number;
     counts: Record<EmailMessageStatus, number>;
+    /**
+     * Delivery lifecycle, when the send was QUEUED. `null` means the send was
+     * delivered inline (small transactional sends) and already finished — treat
+     * null as done, never as unknown.
+     */
+    status: EmailBatchLifecycle | null;
+    /** Delivery-chunk progress, when queued. Null otherwise. */
+    chunksTotal: number | null;
+    chunksDone: number | null;
+    /** Recipients not yet attempted, when queued. Null otherwise. */
+    pending: number | null;
 }
 interface EmailSuppression {
     id: string;
@@ -3018,7 +3070,155 @@ interface EmailWindowOptions {
     start?: string | Date;
     end?: string | Date;
 }
+/**
+ * How a message body is interpreted.
+ *
+ * `auto` (the default) sniffs it: something that looks like HTML is sent as HTML,
+ * anything else is rendered from Markdown. Every message goes out multipart with a
+ * plain-text alternative derived from the body, which mail providers reward.
+ */
+type EmailBodyType = 'auto' | 'html' | 'markdown' | 'text';
+interface EmailAttachmentInput {
+    url: string;
+    /** Displayed filename. Derived from the URL when omitted. */
+    filename?: string;
+    contentType?: string;
+}
+interface EmailSendOptions {
+    /** Visible recipients. Optional only if you supply `cc` or `bcc`. */
+    to?: string | string[];
+    cc?: string | string[];
+    /**
+     * Hidden recipients. With no `to`/`cc`, the To: header is addressed to your
+     * app's own sender — the standard "undisclosed recipients" pattern — so
+     * recipients can't see each other.
+     */
+    bcc?: string | string[];
+    subject: string;
+    /** Plain text, Markdown, or HTML. See {@link EmailBodyType}. */
+    body: string;
+    bodyType?: EmailBodyType;
+    /** Your own plain-text alternative, instead of the auto-derived one. */
+    text?: string;
+    attachments?: Array<string | EmailAttachmentInput>;
+    /**
+     * Sender handle — only if your app has a custom domain or platform subdomain.
+     * `"support"`, `"support@your-domain.com"`, or `"Name <support@your-domain.com>"`.
+     * The domain must be one your app owns or the send fails.
+     */
+    from?: string;
+    replyTo?: string;
+    /** Message-ID this replies to, for threading in a shared inbox. */
+    inReplyTo?: string;
+    /** Prior Message-IDs in the thread. */
+    references?: string[];
+    /**
+     * **Defaults to `marketing`**, which is the consequential choice here.
+     *
+     * `marketing` attaches a one-click unsubscribe header pointing at your own
+     * domain and skips anyone who previously unsubscribed from your app. Because
+     * that link is per-recipient, a marketing send delivers one separate message per
+     * recipient and `cc`/`bcc` are folded into that list — so they come back empty.
+     *
+     * `transactional` is for receipts, alerts and password resets: no unsubscribe
+     * header, the unsubscribe list is ignored, and `cc`/`bcc` stay on one shared
+     * message. Use it whenever cc/bcc semantics actually matter.
+     */
+    category?: 'transactional' | 'marketing';
+    /**
+     * Groups this send's per-recipient rows into one blast. Pass your own campaign
+     * id (1–64 printable chars) to join our delivery stats onto your own tables with
+     * no mapping; one is generated when omitted, and it's always returned.
+     */
+    batchId?: string;
+}
+interface EmailSendResult {
+    /** Addresses the message went to. */
+    recipients: string[];
+    /** Always empty for a marketing send — see `category`. */
+    cc: string[];
+    /** Always empty for a marketing send — see `category`. */
+    bcc: string[];
+    /** The resolved sender it went out as. */
+    from: string;
+    /**
+     * Recipients skipped because they had unsubscribed from your app. **Not an
+     * error** — the send succeeded and we honoured their opt-out. Always empty for
+     * a transactional send.
+     *
+     * Worth surfacing to whoever triggered the send: "sent to 48 of 50, 2
+     * unsubscribed" is the honest report, and silence here is what makes people
+     * think mail vanished.
+     */
+    suppressed: string[];
+    /** Read stats back with `email.batch(batchId)`. */
+    batchId: string;
+}
+/** Your app's sending allowance for the current window. */
+interface EmailQuota {
+    /** What the numbers count — `recipients`. */
+    unit: string;
+    window: 'day' | 'month' | 'total';
+    /** `null` means unlimited. */
+    limit: number | null;
+    used: number;
+    /** `null` when `limit` is null. */
+    remaining: number | null;
+    /** When `used` resets. */
+    resetsAt: string | null;
+}
 interface Email {
+    /**
+     * Send an email.
+     *
+     * Two things to know before your first call. **`category` defaults to
+     * `marketing`**, which fans a multi-recipient send out into one message each and
+     * empties `cc`/`bcc` — pass `'transactional'` for receipts, alerts and codes.
+     * And a non-empty `suppressed` in the result is a **success**, not a failure: it
+     * lists people who had unsubscribed and were therefore skipped.
+     *
+     * Delivery is split from acceptance: small transactional sends deliver before
+     * this resolves; marketing and large sends are QUEUED — this resolves once the
+     * send is accepted, and delivery continues in the background. Track progress
+     * with `email.batch(batchId)` (`status`, `pending`, chunk counts); outcomes
+     * (delivered, bounced, complained) arrive later on `email.messages({ batchId })`.
+     *
+     * Throws `outbound_daily_cap_exceeded` (429) over the app's daily recipient
+     * quota — check `email.quota()` before a big send — and `sending_paused` (409)
+     * when the app's sending is paused for reputation or by support; a 409 will
+     * not succeed on retry.
+     *
+     * @example
+     * ```ts
+     * // A receipt: one message, cc preserved, no unsubscribe header.
+     * await email.send({
+     *   to: 'customer@example.com',
+     *   cc: 'billing@your-co.com',
+     *   subject: 'Your receipt',
+     *   body: '# Thanks!\n\nOrder #1234 is confirmed.',
+     *   category: 'transactional',
+     * });
+     *
+     * // A campaign: per-recipient unsubscribe, your own id for joining stats.
+     * const { suppressed, batchId } = await email.send({
+     *   to: subscribers,
+     *   subject: 'August newsletter',
+     *   body: markdown,
+     *   batchId: 'newsletter-2026-08',
+     * });
+     * console.log(`skipped ${suppressed.length} unsubscribed`);
+     * const stats = await email.batch(batchId);
+     * ```
+     */
+    send(options: EmailSendOptions): Promise<EmailSendResult>;
+    /**
+     * Your app's sending allowance and how much is left.
+     *
+     * Useful before a large send: check `remaining` and split the list rather than
+     * discovering the limit as a failure partway through. Going over throws with
+     * `outbound_daily_cap_exceeded`.
+     */
+    quota(): Promise<EmailQuota>;
     /** Counts, rates and a timeseries over a window (default: last 24h). */
     stats(options?: EmailWindowOptions & {
         buckets?: number;
@@ -3038,7 +3238,7 @@ interface Email {
     }>;
     /** One message, including bounce diagnostics. */
     message(messageId: string): Promise<EmailMessage>;
-    /** One row per blast, newest first. */
+    /** One row per blast, newest first, with delivery lifecycle where queued. */
     batches(options?: EmailWindowOptions & {
         limit?: number;
         offset?: number;
@@ -3046,7 +3246,11 @@ interface Email {
         batches: EmailBatch[];
         total: number;
     }>;
-    /** Stats for a single blast — the id you passed to `sendEmail`, or the one it returned. */
+    /**
+     * Stats and delivery progress for a single blast — the id you passed to
+     * `email.send()`, or the one it returned. Poll this to watch a queued send
+     * drain (`status`, `pending`, chunk counts).
+     */
     batch(batchId: string): Promise<EmailBatch>;
     /** Your app's unsubscribe list, newest first. */
     suppressions(options?: {
@@ -3738,13 +3942,25 @@ declare class MindStudioAgent$1 {
      */
     get analytics(): Analytics;
     /**
-     * Outbound email: the per-recipient delivery log, blast stats, and this app's
-     * unsubscribe list. Sending is the `sendEmail` action, not this namespace.
+     * Outbound email: sending, the per-recipient delivery log, blast stats, and
+     * this app's unsubscribe list.
+     *
+     * `email.send()` is the send path — the `sendEmail` action still works and runs
+     * the same code, but `send()` returns a receipt including the `batchId` you read
+     * stats back with. Note `category` defaults to `'marketing'`; see
+     * {@link Email.send}.
      *
      * @example
      * ```ts
      * import { email } from '@mindstudio-ai/agent';
      *
+     * await email.send({
+     *   to: 'a@b.com',
+     *   subject: 'Your receipt',
+     *   body: 'Thanks!',
+     *   category: 'transactional',
+     * });
+     *
      * // A support lookup: did this person get their mail?
      * const { messages } = await email.messages({ recipient: 'a@b.com' });
      *
@@ -7219,6 +7435,8 @@ interface SendEmailStepInput {
     references?: string[];
     /** `marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message. */
     category?: "transactional" | "marketing";
+    /** Groups this send's per-recipient rows into one blast, so per-campaign stats are readable afterwards. Pass your own campaign id (1-64 printable chars) to join our delivery stats onto your own tables with no mapping; omit it and one is generated. Either way it comes back in the output. */
+    batchId?: string;
 }
 interface SendEmailStepOutput {
     /** To addresses the message was sent to. */
@@ -7231,6 +7449,8 @@ interface SendEmailStepOutput {
     from: string;
     /** Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send. */
     suppressed: string[];
+    /** Groups this send's per-recipient rows into one blast — the caller's `batchId` if supplied, otherwise a generated one. Returned unconditionally so an app can read per-blast stats back without having had to pass anything. */
+    batchId: string;
 }
 interface SendGmailDraftStepInput {
     /** Gmail draft ID to send */
@@ -10318,6 +10538,7 @@ interface StepMethods {
      * Send an email to one or more recipient addresses.
      *
      * @remarks
+     * - If you are writing a backend method for a v2 app, prefer mindstudio.email.send({...}) — it takes the same fields, returns the batchId you read stats back with, and sits alongside email.messages / email.batch / email.suppress. This action remains fully supported and runs the same code; it is also the only way to use connectionId or generateHtml.
      * - Use the "to" field to send to one or more specific recipient email addresses directly. Allowed recipients depend on the sender: when the app sends from a domain it owns (a verified custom domain or its <slug>.madewithremy.com subdomain) any recipient is allowed; when it falls back to the shared Remy address, recipients must be verified app users or members of the app's organization. (v1 apps cannot use a direct "to" — they must resolve recipients via a connection.)
      * - Alternatively, recipient email addresses can be resolved from OAuth connections configured by the app creator via connectionId. The user running the workflow does not specify the recipient directly.
      * - Use "cc" and "bcc" to add visible / hidden recipients (a string or an array). They are subject to the same recipient rules as "to".
@@ -10338,7 +10559,7 @@ interface StepMethods {
      * - The special connectionId "trigger_email" uses the email address that triggered the workflow.
      * - Sends default to category "marketing": every message carries a one-click unsubscribe header pointing at the app's own domain, and recipients who previously unsubscribed from this app are skipped and returned in "suppressed". Because the unsubscribe link is per-recipient, a marketing send delivers one separate message per recipient and cc/bcc are folded into that list.
      * - Set category to "transactional" for receipts, alerts, password resets and anything a recipient must not be able to opt out of. Transactional sends carry no unsubscribe header, ignore the unsubscribe list, and keep cc/bcc on a single message — use it whenever cc/bcc semantics matter.
-     * - The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject — no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body, which is never stored.
+     * - The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject — no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body of a "transactional" send: a small transactional send is delivered immediately and its body is never stored. A "marketing" send, or any large send, is queued for delivery, which means its body is held in internal storage until the send finishes — so do not put a secret in the body of one of those either.
      *
      * @example
      * ```typescript
@@ -11205,11 +11426,15 @@ declare const voice: Voice;
  */
 declare const analytics: Analytics;
 /**
- * Your app's outbound email — the delivery log, blast stats, and the unsubscribe
- * list. Sending is `mindstudio.sendEmail(...)`; this is everything after it.
+ * Your app's outbound email — sending, the delivery log, blast stats, and the
+ * unsubscribe list.
+ *
+ * `email.send()` is the send path. `mindstudio.sendEmail(...)` still works and
+ * runs the same code underneath, but `send()` returns a proper receipt and sits
+ * next to everything you do with the result.
  *
  * Scoped to the executing app by its request token, so there is no appId to pass
- * and no way to read another app's mail.
+ * and no way to read or send as another app.
  *
  * @example
  * ```ts

package/dist/index.js

@@ -3026,6 +3026,12 @@ function createAnalytics(call) {
 var iso = (v) => v === void 0 ? void 0 : v instanceof Date ? v.toISOString() : v;
 function createEmail(call) {
   return {
+    send(options) {
+      return call("send", options);
+    },
+    quota() {
+      return call("quota", {});
+    },
     stats(options) {
       return call("stats", {
         start: iso(options?.start),
@@ -4030,7 +4036,8 @@ var stepMetadata = {
   "sendEmail": {
     stepType: "sendEmail",
     description: "Send an email to one or more recipient addresses.",
-    usageNotes: `- Use the "to" field to send to one or more specific recipient email addresses directly. Allowed recipients depend on the sender: when the app sends from a domain it owns (a verified custom domain or its <slug>.madewithremy.com subdomain) any recipient is allowed; when it falls back to the shared Remy address, recipients must be verified app users or members of the app's organization. (v1 apps cannot use a direct "to" \u2014 they must resolve recipients via a connection.)
+    usageNotes: `- If you are writing a backend method for a v2 app, prefer mindstudio.email.send({...}) \u2014 it takes the same fields, returns the batchId you read stats back with, and sits alongside email.messages / email.batch / email.suppress. This action remains fully supported and runs the same code; it is also the only way to use connectionId or generateHtml.
+- Use the "to" field to send to one or more specific recipient email addresses directly. Allowed recipients depend on the sender: when the app sends from a domain it owns (a verified custom domain or its <slug>.madewithremy.com subdomain) any recipient is allowed; when it falls back to the shared Remy address, recipients must be verified app users or members of the app's organization. (v1 apps cannot use a direct "to" \u2014 they must resolve recipients via a connection.)
 - Alternatively, recipient email addresses can be resolved from OAuth connections configured by the app creator via connectionId. The user running the workflow does not specify the recipient directly.
 - Use "cc" and "bcc" to add visible / hidden recipients (a string or an array). They are subject to the same recipient rules as "to".
 - "to" is optional only in the sense that recipients can come from elsewhere \u2014 omit it and supply "cc"/"bcc" for a hidden-list send, or omit all three and recipients are resolved from an OAuth connection. Naming nobody at all is an error.
@@ -4050,9 +4057,9 @@ var stepMetadata = {
 - The special connectionId "trigger_email" uses the email address that triggered the workflow.
 - Sends default to category "marketing": every message carries a one-click unsubscribe header pointing at the app's own domain, and recipients who previously unsubscribed from this app are skipped and returned in "suppressed". Because the unsubscribe link is per-recipient, a marketing send delivers one separate message per recipient and cc/bcc are folded into that list.
 - Set category to "transactional" for receipts, alerts, password resets and anything a recipient must not be able to opt out of. Transactional sends carry no unsubscribe header, ignore the unsubscribe list, and keep cc/bcc on a single message \u2014 use it whenever cc/bcc semantics matter.
-- The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject \u2014 no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body, which is never stored.`,
-    inputSchema: { "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content (plain text, markdown, HTML, or a CDN URL to an HTML file)" }, "to": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "cc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "bcc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "connectionId": { "type": "string", "description": "OAuth connection ID(s) for the recipient(s), comma-separated for multiple" }, "generateHtml": { "type": "boolean", "description": "When true, auto-convert the body text into a styled HTML email using AI" }, "generateHtmlInstructions": { "type": "string", "description": "Natural language instructions for the HTML generation style" }, "generateHtmlModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": 'Model identifier (e.g. "gpt-4", "claude-3-opus")' }, "temperature": { "type": "number", "description": "Sampling temperature for the model (0-2)" }, "maxResponseTokens": { "type": "number", "description": "Maximum number of tokens in the model's response" }, "ignorePreamble": { "type": "boolean", "description": "Whether to skip the system preamble/instructions" }, "userMessagePreprocessor": { "type": "object", "properties": { "dataSource": { "type": "string", "description": "Data source identifier for the preprocessor" }, "messageTemplate": { "type": "string", "description": "Template string applied to user messages before sending to the model" }, "maxResults": { "type": "number", "description": "Maximum number of results to include from the data source" }, "enabled": { "type": "boolean", "description": "Whether the preprocessor is active" }, "shouldInherit": { "type": "boolean", "description": "Whether child steps should inherit this preprocessor configuration" } }, "description": "Preprocessor applied to user messages before sending to the model" }, "preamble": { "type": "string", "description": "System preamble/instructions for the model" }, "multiModelEnabled": { "type": "boolean", "description": "Whether multi-model candidate generation is enabled" }, "editResponseEnabled": { "type": "boolean", "description": "Whether the user can edit the model's response" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model settings override for HTML generation" }, "attachments": { "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url"] }] }, "description": "Files to attach: each entry is a URL string, or an object `{ url, filename?, contentType? }` to control the displayed filename and MIME type." }, "from": { "type": "string", "description": "Custom sender handle \u2014 only for apps with a custom domain or subdomain. Bare handle (`support`), full `support@your-domain.com`, or `Name <support@your-domain.com>`. Must resolve to a domain the app owns." }, "bodyType": { "enum": ["auto", "html", "markdown", "text"], "type": "string", "description": "How to interpret `body`: `auto` (default \u2014 detect HTML, else render markdown), `html` (send as-is), `markdown` (render to HTML), or `text` (send as plain text only, no HTML part). Every send includes a text/plain alternative." }, "text": { "type": "string", "description": "Explicit text/plain alternative body. Auto-derived from `body` if omitted." }, "replyTo": { "type": "string", "description": "Reply-To address for the email." }, "inReplyTo": { "type": "string", "description": "Message-ID this email replies to, for inbox threading (In-Reply-To header)." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Prior Message-IDs in the thread, for inbox threading (References header)." }, "category": { "enum": ["transactional", "marketing"], "type": "string", "description": "`marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message." } }, "required": ["subject", "body"] },
-    outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "To addresses the message was sent to." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Cc addresses on the message (empty if none)." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Bcc addresses on the message (empty if none)." }, "from": { "type": "string", "description": "The resolved sender address the message went out as (auto-selected when no `from` is given)." }, "suppressed": { "type": "array", "items": { "type": "string" }, "description": "Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send." } }, "required": ["recipients", "cc", "bcc", "from", "suppressed"] }
+- The subject is stored verbatim in the app's delivery log, which every workspace member can read for 90 days. Never put a secret in the subject \u2014 no one-time codes, no magic-link tokens, no password-reset tokens. Put those in the body of a "transactional" send: a small transactional send is delivered immediately and its body is never stored. A "marketing" send, or any large send, is queued for delivery, which means its body is held in internal storage until the send finishes \u2014 so do not put a secret in the body of one of those either.`,
+    inputSchema: { "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content (plain text, markdown, HTML, or a CDN URL to an HTML file)" }, "to": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "cc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "bcc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "connectionId": { "type": "string", "description": "OAuth connection ID(s) for the recipient(s), comma-separated for multiple" }, "generateHtml": { "type": "boolean", "description": "When true, auto-convert the body text into a styled HTML email using AI" }, "generateHtmlInstructions": { "type": "string", "description": "Natural language instructions for the HTML generation style" }, "generateHtmlModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": 'Model identifier (e.g. "gpt-4", "claude-3-opus")' }, "temperature": { "type": "number", "description": "Sampling temperature for the model (0-2)" }, "maxResponseTokens": { "type": "number", "description": "Maximum number of tokens in the model's response" }, "ignorePreamble": { "type": "boolean", "description": "Whether to skip the system preamble/instructions" }, "userMessagePreprocessor": { "type": "object", "properties": { "dataSource": { "type": "string", "description": "Data source identifier for the preprocessor" }, "messageTemplate": { "type": "string", "description": "Template string applied to user messages before sending to the model" }, "maxResults": { "type": "number", "description": "Maximum number of results to include from the data source" }, "enabled": { "type": "boolean", "description": "Whether the preprocessor is active" }, "shouldInherit": { "type": "boolean", "description": "Whether child steps should inherit this preprocessor configuration" } }, "description": "Preprocessor applied to user messages before sending to the model" }, "preamble": { "type": "string", "description": "System preamble/instructions for the model" }, "multiModelEnabled": { "type": "boolean", "description": "Whether multi-model candidate generation is enabled" }, "editResponseEnabled": { "type": "boolean", "description": "Whether the user can edit the model's response" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model settings override for HTML generation" }, "attachments": { "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url"] }] }, "description": "Files to attach: each entry is a URL string, or an object `{ url, filename?, contentType? }` to control the displayed filename and MIME type." }, "from": { "type": "string", "description": "Custom sender handle \u2014 only for apps with a custom domain or subdomain. Bare handle (`support`), full `support@your-domain.com`, or `Name <support@your-domain.com>`. Must resolve to a domain the app owns." }, "bodyType": { "enum": ["auto", "html", "markdown", "text"], "type": "string", "description": "How to interpret `body`: `auto` (default \u2014 detect HTML, else render markdown), `html` (send as-is), `markdown` (render to HTML), or `text` (send as plain text only, no HTML part). Every send includes a text/plain alternative." }, "text": { "type": "string", "description": "Explicit text/plain alternative body. Auto-derived from `body` if omitted." }, "replyTo": { "type": "string", "description": "Reply-To address for the email." }, "inReplyTo": { "type": "string", "description": "Message-ID this email replies to, for inbox threading (In-Reply-To header)." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Prior Message-IDs in the thread, for inbox threading (References header)." }, "category": { "enum": ["transactional", "marketing"], "type": "string", "description": "`marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message." }, "batchId": { "type": "string", "description": "Groups this send's per-recipient rows into one blast, so per-campaign stats are readable afterwards. Pass your own campaign id (1-64 printable chars) to join our delivery stats onto your own tables with no mapping; omit it and one is generated. Either way it comes back in the output." } }, "required": ["subject", "body"] },
+    outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "To addresses the message was sent to." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Cc addresses on the message (empty if none)." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Bcc addresses on the message (empty if none)." }, "from": { "type": "string", "description": "The resolved sender address the message went out as (auto-selected when no `from` is given)." }, "suppressed": { "type": "array", "items": { "type": "string" }, "description": "Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send." }, "batchId": { "type": "string", "description": "Groups this send's per-recipient rows into one blast \u2014 the caller's `batchId` if supplied, otherwise a generated one. Returned unconditionally so an app can read per-blast stats back without having had to pass anything." } }, "required": ["recipients", "cc", "bcc", "from", "suppressed", "batchId"] }
   },
   "sendGmailDraft": {
     stepType: "sendGmailDraft",
@@ -6824,13 +6831,25 @@ var MindStudioAgent = class {
     );
   }
   /**
-   * Outbound email: the per-recipient delivery log, blast stats, and this app's
-   * unsubscribe list. Sending is the `sendEmail` action, not this namespace.
+   * Outbound email: sending, the per-recipient delivery log, blast stats, and
+   * this app's unsubscribe list.
+   *
+   * `email.send()` is the send path — the `sendEmail` action still works and runs
+   * the same code, but `send()` returns a receipt including the `batchId` you read
+   * stats back with. Note `category` defaults to `'marketing'`; see
+   * {@link Email.send}.
    *
    * @example
    * ```ts
    * import { email } from '@mindstudio-ai/agent';
    *
+   * await email.send({
+   *   to: 'a@b.com',
+   *   subject: 'Your receipt',
+   *   body: 'Thanks!',
+   *   category: 'transactional',
+   * });
+   *
    * // A support lookup: did this person get their mail?
    * const { messages } = await email.messages({ recipient: 'a@b.com' });
    *
@@ -7799,7 +7818,7 @@ var monacoSnippets = {
   "searchXPosts": { fields: [["query", "string"], ["scope", ["recent", "all"]], ["options", "object"]], outputKeys: ["posts"] },
   "searchYoutube": { fields: [["query", "string"], ["limitPages", "string"], ["filter", "string"], ["filterType", "string"]], outputKeys: ["results"] },
   "searchYoutubeTrends": { fields: [["bp", ["now", "music", "gaming", "films"]], ["hl", "string"], ["gl", "string"]], outputKeys: [] },
-  "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients", "cc", "bcc", "from", "suppressed"] },
+  "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients", "cc", "bcc", "from", "suppressed", "batchId"] },
   "sendGmailDraft": { fields: [["draftId", "string"]], outputKeys: [] },
   "sendGmailMessage": { fields: [["to", "string"], ["subject", "string"], ["message", "string"], ["messageType", ["plain", "html", "markdown"]]], outputKeys: ["messageId"] },
   "sendSlackDirectMessage": { fields: [["slackUserId", "string"], ["messageType", ["string", "blocks"]], ["message", "string"]], outputKeys: [] },