Email (email)

Category: io | Form: | Symbol: Em

Connect flows to email for sending and receiving messages via SMTP/IMAP

Unified email connector — receives and sends email depending on wiring topology. When the trigger port is exposed (unwired input), acts as a receiver: inbound mail matching the configured addresses is delivered via NATS and emitted on the message output port. When the request port is driven (wired from another element), acts as a sender: composes and sends email via authenticated SMTP submission. Configure spec.credential_ref with a secret element containing SMTP username and password. For inbound: spec.accepted_addresses controls which recipients are routed to this element. For outbound: spec.from_address sets the sender. Supports HTML bodies, attachments, CC/BCC, reply threading (In-Reply-To/References headers), and open/click tracking. The mail server (Stalwart) handles DKIM signing, SPF, and DMARC automatically. Common mistake: missing credential_ref — send operations will fail.

Guide

Connect flows to email for sending and receiving messages via SMTP/IMAP

What It Does

Email is an IO connector that bridges your Triform flows with email over SMTP (sending) and JMAP/IMAP (receiving). It is a unified connector whose behaviour depends on wiring topology: when the trigger port is exposed (unwired input) it acts as a receiver — inbound mail matching the configured addresses is delivered via NATS and emitted on the message output port; when the request port is driven (wired from another element) it acts as a sender — composing and sending mail via authenticated SMTP submission.

Outbound mail supports plain text and HTML bodies (multipart/alternative), CC/BCC, reply threading (In-Reply-To / References headers), attachments, and open/click tracking. The platform mail server (Stalwart) handles DKIM signing, SPF, and DMARC automatically for platform-managed domains, so no DNS work is needed for triform.wtf, triform.dev, or triform.cloud. Custom sending domains are registered with add_domain and verified with verify_domain before they can be used as a from_address.

Configure spec.credential_ref with a secret element holding the SMTP username and password — or set spec.stalwart_managed = true to use the circle’s built-in Stalwart mailbox ({circle}@triform.wtf), in which case no credential is required. For inbound, spec.accepted_addresses (or spec.accepted_domains) controls which recipients route to this element; for outbound, spec.from_address sets the sender.

Element Definition

Property	Value
Type	email
Category	io
Form	atom
Handler	EmailHandler
Activity type	connector
Delivery mode	async (exponential retry, max 3)
Streaming	not supported

Properties

Field	Type	Default	Description
mode	string	invoke	Inbound routing: invoke (one-shot per message) or conversation (thread per sender)
stalwart_managed	boolean	false	Use the circle’s built-in Stalwart mailbox; credential_ref not required
send_policy	string	auto	Outbound policy: auto, outbox (queue for approval), known_only (refuse unknown recipients)
auto_send_to_unknown	boolean	true	DEPRECATED — use send_policy (true → auto, false → known_only)
credential_ref	string	—	Reference to a secret element with SMTP username/password (not needed when stalwart_managed)
from_address	string	—	Sender email address; must use triform.wtf, triform.dev, or triform.cloud
from_name	string	Triform	Sender display name
reply_to	string	—	Reply-To address (if different from from_address)
smtp_host	string	""	SMTP server hostname (defaults to platform mail server)
smtp_port	integer	587	SMTP submission port
use_tls	boolean	true	Require STARTTLS for SMTP submission
accepted_addresses	array	—	Addresses this element receives mail for
accepted_domains	array	—	Accept all addresses at these domains (overrides accepted_addresses)
default_subject	string	Message from Triform	Subject used when none provided in input
html_enabled	boolean	true	Send HTML bodies (multipart/alternative with text fallback)
tracking_enabled	boolean	false	Enable open/click tracking (inserts pixel, rewrites links)
max_retries	integer	3	Maximum delivery retry attempts
retry_backoff_ms	integer	2000	Base exponential backoff between retries (ms)

Ports

Port	Direction	Type	Description
trigger	input	event	Inbound email — exposed = receiver, listens for mail to accepted addresses
request	input	request	Email to send — driven = sender
message	output	event	Parsed inbound email forwarded into the flow
result	output	event	Send result with message ID and delivery status

Capabilities

smtp-send, smtp-receive, html-multipart, threading, attachments, open-tracking, click-tracking, dkim-spf-dmarc.

Contract attachments

Attaches rate-limit and auth-policy modifiers; uses variable.

Error Codes

Code	Class	Retryable	Description
EMAIL_AUTH_FAILED	auth	no	SMTP authentication failed (invalid credentials)
EMAIL_SEND_FAILED	internal	yes	Failed to send email via SMTP
EMAIL_INVALID_ADDRESS	validation	no	One or more recipient addresses are invalid
EMAIL_REJECTED	internal	no	Remote server rejected the message (permanent failure)
EMAIL_RATE_LIMITED	internal	yes	SMTP rate limit exceeded
EMAIL_TOO_LARGE	validation	no	Message exceeds maximum size limit
EMAIL_CREDENTIAL_MISSING	auth	no	credential_ref not set or referenced secret not found
EMAIL_INVALID_DOMAIN	validation	no	Domain not allowed — only triform.wtf, triform.dev, triform.cloud permitted
EMAIL_ALIAS_EXISTS	validation	no	Email alias already exists on this account

Additional operation-level error codes referenced by op hints: EMAIL_DOMAIN_OWNED_BY_OTHER_CIRCLE, EMAIL_DOMAIN_NOT_VERIFIED, EMAIL_DOMAIN_NOT_REGISTERED, EMAIL_NO_CONSENT, EMAIL_UNKNOWN_RECIPIENT, EMAIL_OUTBOX_INVALID_STATE.

Operations

Sending

send — POST send (auth: write)

Composes and sends an email via SMTP submission. Requires spec.credential_ref and spec.from_address (or spec.stalwart_managed=true). Recipients (to / cc / bcc) accept either a single email string or an array of strings. Supports plain text and HTML (multipart/alternative); set in_reply_to to add threading headers. If from_address points at a domain this circle does not own + verify, the send is refused (403 EMAIL_DOMAIN_OWNED_BY_OTHER_CIRCLE, 412 EMAIL_DOMAIN_NOT_VERIFIED, or 412 EMAIL_DOMAIN_NOT_REGISTERED), or the From is rewritten to the platform mailbox (from_rewritten=true). Required input: to, subject, body.

send_tracked — POST send_tracked (auth: write)

Campaign-style single-recipient send with consent gate, open/click tracking, and audit trail. Applies the same compliance gates as send plus a consent check: the contact must have consent_status of soft_optin or double_optin, otherwise refused with EMAIL_NO_CONSENT. The HTML body is rewritten to inject an open-tracking pixel and link redirects. Wrap in a loop element to send to multiple contacts. Required input: to, subject.

reply — POST reply (auth: write)

Convenience operation for replying to an inbound email. Automatically sets In-Reply-To, References, and the To address from the original message; the subject is prefixed with “Re: “ if not already present. Required input: original_message_id, body.

Inbox (read / manage)

list-inbox — GET list-inbox (auth: read)

Lists message envelopes in a folder (default INBOX) via JMAP, paginated with page_token. Returns envelopes (id, from, subject, date, read status) without bodies.

get-message — GET get-message (auth: read)

Retrieves the full message including text and HTML body, headers, and attachment metadata. Automatically marks the message as read. Required input: message_id.

search — GET search (auth: read)

Full-text search across message subjects, bodies, and sender addresses via JMAP Email/query. Required input: query.

unread-count — GET unread-count (auth: read)

Returns the number of unread messages in the inbox.

mark-read — POST mark-read (auth: write)

Sets the $seen JMAP keyword on the specified message. Required input: message_id.

delete-message — POST delete-message (auth: write)

Permanently deletes a message via JMAP Email/set destroy (Stalwart typically moves to Trash first; a second delete expunges). Required input: message_id.

Folders & labels

list_folders — POST list_folders (auth: read)

Returns every folder in the mailbox (Inbox, Sent, Drafts, Trash, Junk, and user-created), each with id, name, role, parent_id, total_emails, and unread_emails.

create_folder — POST create_folder (auth: write)

Creates a new mailbox folder (Mailbox/set create). Pass parent_id for nested folders. Required input: name.

move_to_folder — POST move_to_folder (auth: write)

Updates a message’s mailboxIds. Pass folder_id (string) for an exclusive move or folder_ids (array) to file into multiple folders. Required input: message_id.

apply_label — POST apply_label (auth: write)

Sets a JMAP keyword on a message (avoid $ prefix for user labels). Required input: message_id, label.

remove_label — POST remove_label (auth: write)

Clears a previously-applied keyword (idempotent). Required input: message_id, label.

Addresses

provision-address — POST provision-address (auth: write)

Provisions a new email address/alias on the mail server for this circle. Only triform.wtf, triform.dev, and triform.cloud domains are allowed; external domains are rejected. Idempotent — re-calling an already-provisioned address returns provisioned:false, already_exists:true. Required input: address.

remove-address — POST remove-address (auth: write)

Removes an email alias. Cannot remove the primary circle address. Required input: address.

list-addresses — GET list-addresses (auth: read)

Returns all provisioned addresses/aliases for this circle’s mail account, including the primary address.

Managed mailbox & sending domains

bootstrap_managed_domain — POST bootstrap_managed_domain (auth: write)

One-shot setup for the platform-managed mailbox path: ensures the circle’s Stalwart account exists, optionally provisions an alias on a platform-managed domain, and sets stalwart_managed=true plus from_address. After it returns, send works with no further configuration (the platform owns DKIM/SPF/DMARC). Idempotent.

add_domain — POST add_domain (auth: write)

Registers a custom sending domain and returns the DNS TXT records the operator must publish before verify_domain succeeds. Until verified, sends from this domain fall back to the platform mailbox. Idempotent for the same circle; cross-circle attempts return 403 EMAIL_DOMAIN_OWNED_BY_OTHER_CIRCLE. Required input: domain.

verify_domain — POST verify_domain (auth: write)

Runs a DNS TXT lookup and flips the domain to verified on success. Re-run after publishing the verification record. Required input: domain.

list_domains — POST list_domains (auth: read)

Lists custom sending domains registered to this circle; each entry carries verified.

remove_domain — POST remove_domain (auth: write)

Drops a custom sending domain from the registry; sends from it fall back to the platform mailbox. Required input: domain.

Outbox (approval queue)

Active when spec.send_policy = "outbox" — sends are queued as drafts and dispatched only on approval.

list_outbox — POST list_outbox (auth: read)

Returns outbox rows for this element, filterable by status (default pending). Each row includes the draft payload for review.

approve_dispatch — POST approve_dispatch (auth: write)

Approves a queued draft and dispatches it via SMTP. Only pending rows can be approved; repeat approvals return EMAIL_OUTBOX_INVALID_STATE. Required input: dispatch_id.

reject_dispatch — POST reject_dispatch (auth: write)

Rejects a queued draft without sending, recording an optional reason. Required input: dispatch_id.

Compliance & diagnostics

test_connection — POST test-connection (auth: execute)

Connects to the configured SMTP server, performs EHLO and authentication, and returns server capabilities and auth status. Does not send any email.

rate-status — GET rate-status (auth: read)

Reads the current daily send-rate counter and the configured cap (default 500/day, EMAIL_DAILY_CAP_PER_CIRCLE override), including remaining and the next UTC-midnight reset_at.

list-suppressions — GET list-suppressions (auth: read)

Lists suppressed addresses for this circle (deliverability protection list), with reason, source, notes, and created_at.

add-suppression — POST add-suppression (auth: write)

Manually adds an address to the suppression list (records source=manual_user). Idempotent. Required input: address.

remove-suppression — POST remove-suppression (auth: admin)

Removes an address from the suppression list, re-permitting mail. Audit-sensitive: reason is mandatory. Required input: address, reason.

list-events — GET list-events (auth: read)

Reads the per-circle email audit log (sent / opened / clicked / bounced / suppressed / unsuppressed / consent_changed / campaign_started / campaign_finished), filterable by event_type or address.

Quick Start

Create the element configured for the platform-managed mailbox, then send a test email:

// 1. Create an email element (managed mailbox — no credential or DNS needed)
// spec:
{
  "stalwart_managed": true,
  "from_address": "support@triform.wtf",
  "from_name": "Acme Support"
}

// 2. Verify SMTP connectivity
//    POST /api/{circle}/{slug}/ops/test-connection

// 3. Send an email
//    POST /api/{circle}/{slug}/ops/send
{
  "to": "test@example.com",
  "subject": "Hello from Triform",
  "body": "Test email",
  "html": "<p>Test email</p>"
}

For external SMTP instead of the managed mailbox, set credential_ref to a secret element holding the SMTP username/password and leave stalwart_managed unset.

To receive mail, expose the trigger port and set accepted_addresses (or accepted_domains) to the addresses this element should listen for; inbound mail is emitted on the message output port.

Common Mistakes

• Missing credential_ref for external SMTP. Send operations fail with EMAIL_CREDENTIAL_MISSING unless stalwart_managed is true. (validation: credential_required_for_send)
• from_address on a non-Triform domain. from_address must end in @triform.wtf, @triform.dev, or @triform.cloud (error-severity validation from_address_domain_validation); other domains require add_domain + verify_domain first.
• No inbound addresses configured. Receiving requires accepted_addresses or accepted_domains (waived only when stalwart_managed, which defaults to the circle mailbox). (validation: inbound_addresses_required_for_receive)
• Tracking without HTML. tracking_enabled=true with html_enabled=false has no effect — the open-tracking pixel needs an HTML body. (warning: tracking_enabled && !html_enabled)
• Sending before domain verification. Until verify_domain succeeds, sends from a custom domain silently fall back to the platform mailbox (from_rewritten=true).

Relationships

• Attaches to: rate-limit, auth-policy
• Uses: variable

Capabilities

• smtp-send: Send email via authenticated SMTP submission
• smtp-receive: Receive inbound email via NATS delivery pipeline
• html-multipart: Send HTML emails with automatic plain text fallback
• threading: Reply threading via In-Reply-To and References headers
• attachments: Receive and parse email attachments
• open-tracking: Track email opens via tracking pixel
• click-tracking: Track link clicks via URL rewriting
• dkim-spf-dmarc: Automatic DKIM signing, SPF and DMARC alignment via platform mail server

Properties

Property	Type	Default	Description
mode	string	"invoke"	Inbound routing mode. invoke (default) dispatches each incoming mail to the target_ref element as a one-shot — good for automations that process-and-forget each message. conversation threads every inbound mail from the same sender into a persistent conversation with the target_ref agent, correlating by RFC 5322 References and Message-Id headers — good for auto-responders that need memory across a thread. Outbound replies sent via the agent’s conversation carry the correct threading headers automatically.
stalwart_managed	boolean	false	Platform-managed mailbox. When true, the server uses the circle’s built-in Stalwart mailbox ({circle}@triform.wtf) for sending and receiving. credential_ref is not required in this mode — the server derives SMTP credentials via HMAC. accepted_addresses defaults to the circle’s own mailbox if left empty. Auto-set by the portal when the inbox UI provisions a default email element per circle.
send_policy	string	"auto"	Outbound dispatch policy (IMPROVE-178). Tri-state replacement for the legacy boolean auto_send_to_unknown flag. - auto (default): every send is dispatched immediately to SMTP. Equivalent to legacy auto_send_to_unknown=true. - outbox: every send is queued in the platform’s email_outbox table as a draft with status=pending. The actual SMTP submission happens when an operator (or an attached actions/hitl element) calls approve_dispatch. reject_dispatch discards a draft without sending. Use this when a human (or HITL flow) must review outbound mail before it leaves the system — e.g. agent outreach in a regulated industry. - known_only: equivalent to legacy auto_send_to_unknown=false. Sends are dispatched immediately, but recipients with no prior contact history on this circle are refused with EMAIL_UNKNOWN_RECIPIENT. Replies (in_reply_to set) are exempt — responding to someone who wrote you first always establishes legitimate interest. Known contacts are those present in the circle’s io/contacts element (or its backing table for circles without a contacts element). When this field is unset, the runtime falls back to mapping the legacy auto_send_to_unknown field: true → auto, false → known_only.
auto_send_to_unknown	boolean	true	DEPRECATED — use send_policy instead (IMPROVE-178). When send_policy is unset the runtime falls back to this field: true → auto, false → known_only. New configs should set send_policy directly. Original semantics: when false, outbound sends to addresses with no prior contact history on this circle are refused with EMAIL_UNKNOWN_RECIPIENT instead of reaching SMTP. Replies (in_reply_to set) are exempt. Known contacts are those present in the circle’s io/contacts element (or its backing table for circles without a contacts element).
credential_ref	string	—	Reference to a secret element holding SMTP credentials. The vault secret may be a JSON object {“username”: “…”, “password”: “…”} or a bare password string. Not needed when stalwart_managed is true. Send-side credential precedence: credential_ref (JSON username+password) → else inline smtp_username + smtp_password.
smtp_username	string	—	SMTP submission username for an external (non-Stalwart) mail server — e.g. the full Gmail address when sending through smtp.gmail.com with an app password. Used together with smtp_password when credential_ref is not set. Ignored when stalwart_managed is true (the platform derives SMTP auth via HMAC).
smtp_password	string	—	Reference to a secret element holding the SMTP password / app password for smtp_username. APP-PASSWORD ONLY in this build — for Gmail/Outlook enable 2FA and generate a 16-character app password. Lower precedence than credential_ref. Never store the literal password here; point at a secret element (modifiers/api-token).
mailbox_backend	string	"stalwart"	Which mailbox backend this element reads from. stalwart (default) uses the platform’s built-in Stalwart mailbox over JMAP — existing behavior, unchanged. imap connects to an external IMAP server (Gmail, Outlook, Fastmail, self-hosted, …) with an app password for read/search/manage, and sends via the configured SMTP host. Backend selection is element-agnostic: the runtime treats the element as IMAP when mailbox_backend is “imap” OR imap_host is non-empty. APP-PASSWORD ONLY — there is no OAuth/XOAUTH2 path in this build.
imap_host	string	""	IMAP server hostname for the external mailbox (e.g. imap.gmail.com, outlook.office365.com, imap.fastmail.com). Setting this is sufficient to select the IMAP backend even without mailbox_backend=“imap”. Leave empty for the platform Stalwart mailbox.
imap_port	integer	993	IMAP server port (993 = implicit TLS, 143 = STARTTLS)
use_imap_tls	boolean	true	Use TLS for the IMAP connection. true (default) = implicit TLS on :993; false = STARTTLS upgrade on :143. External providers (Gmail/Outlook/Fastmail) all require TLS.
imap_username	string	—	IMAP login username — usually the full email address (e.g. you@gmail.com). Used together with imap_password when imap_credential_ref is not set.
imap_password	string	—	Reference to a secret element holding the IMAP password / app password for imap_username. APP-PASSWORD ONLY — for Gmail enable 2FA and generate a 16-character app password (regular account passwords are rejected by Gmail IMAP). Lower precedence than imap_credential_ref. Point at a secret element; never store the literal password here.
imap_credential_ref	string	—	Reference to a secret element holding IMAP credentials as a JSON object {“username”: “…”, “password”: “…”}. Read-side credential precedence: imap_credential_ref (JSON username+password) → else inline imap_username + imap_password. APP-PASSWORD ONLY.
from_address	string	—	Sender email address (e.g. noreply@triform.dev)
from_name	string	"Triform"	Sender display name (e.g. ‘Triform Platform’)
reply_to	string	—	Reply-To address (if different from from_address)
smtp_host	string	""	SMTP server hostname (defaults to platform mail server)
smtp_port	integer	587	SMTP submission port
use_tls	boolean	true	Require STARTTLS for SMTP submission
accepted_addresses	array	—	Email addresses this element receives mail for (e.g. [‘support@triform.dev’, ‘info@triform.dev’])
accepted_domains	array	—	Accept all addresses at these domains (e.g. [‘triform.dev’]). Overrides accepted_addresses.
default_subject	string	"Message from Triform"	Default subject line when not provided in input
html_enabled	boolean	true	Send HTML bodies (multipart/alternative with plain text fallback)
tracking_enabled	boolean	false	Enable open and click tracking (inserts tracking pixel and rewrites links)
max_retries	integer	3	Maximum delivery retry attempts
retry_backoff_ms	integer	2000	Base backoff between retries in milliseconds (exponential)

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

add-suppression

Post /ops/add-suppression | Auth: Write

Manually add an address to this circle’s suppression list. Idempotent (no-op if already present).

Use when an operator has out-of-band evidence that an address should not receive mail from this circle (e.g., direct user request, prior fraud signal). Records source=manual_user and emits a SUPPRESSED audit event.

add_domain

Post /ops/add_domain | Auth: Write

Register a custom sending domain (verification still required)

Records the domain against this circle and returns the DNS TXT records the operator must publish before verify-domain will succeed (verification token, SPF include, DKIM hint, DMARC starter). Until verified, sends with from_address pointing at this domain fall back to the platform mailbox — verification is a hard gate to prevent spoofing. Idempotent (BUGS-476): re-calling for a domain already registered to THIS circle returns 200 with added:false, already_exists:true and the original DNS records, so setup scripts can safely re-run. Cross-circle attempts (same domain registered to a different circle) return 403 with EMAIL_DOMAIN_OWNED_BY_OTHER_CIRCLE.

apply_label

Post /ops/apply_label | Auth: Write

Apply a label keyword to a message

Sets a JMAP keyword on the message. JMAP uses keywords for both system flags ($seen, $flagged, $answered) and user labels — convention is to avoid the $-prefix for user labels so they don’t collide with system flags. Labels show up alongside folder membership in modern mail clients (Gmail labels, Apple Mail flags, Thunderbird tags).

approve_dispatch

Post /ops/approve_dispatch | Auth: Write

Approve a queued draft and dispatch it via SMTP

Transitions an outbox row from pending → approved, then re-runs the stored draft_payload through the normal send path with the outbox detour bypassed. On SMTP success the row is updated to sent and the message_id is recorded; on failure the row is updated to failed with error_message set. The dispatch_id argument is the row’s UUID as returned by list_outbox. Only rows currently in pending can be approved — repeat approvals are idempotent against the row’s state machine and return EMAIL_OUTBOX_INVALID_STATE.

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_apply

Post /ops/batch_apply | Auth: Write

Apply read/unread state and folder moves to multiple messages

Use this for mailbox triage batches. Each item needs message_id and at least one mutation: seen=true to mark read, seen=false to mark unread, folder_id for a single target, or folder_ids for multiple JMAP targets. IMAP backends group compatible UID STORE and UID MOVE commands so batches are much faster than calling mark-read and move-to-folder per message.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

bootstrap_managed_domain

Post /ops/bootstrap_managed_domain | Auth: Write

One-shot setup for the platform-managed mailbox path

Single-call email-bootstrap convenience: ensures the circle’s Stalwart account exists, optionally provisions a custom alias on a platform-managed domain (triform.wtf / triform.dev / triform.cloud), and updates this element’s spec to set stalwart_managed=true plus from_address. After this op returns, ops/send works against this element with no further configuration — no DNS work is needed because the platform owns DKIM/SPF/DMARC for the managed domains. Idempotent: safe to call repeatedly. For custom-apex sending domains the operator controls themselves, use ops/add_domain + ops/verify_domain instead.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

create_folder

Post /ops/create_folder | Auth: Write

Create a new mailbox folder

Mailbox/set create. For nested folders (“Clients/Acme”) create the parent first, then pass its id as parent_id when creating the child. Returns the new mailbox id which you’ll use as a folder_id target.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

delete-message

Post /ops/delete-message | Auth: Write

Delete a message

Permanently deletes a message via JMAP Email/set destroy. On most configurations Stalwart moves the message to Trash first; a second delete from Trash expunges it.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

folder_counts

Post /ops/folder_counts | Auth: Read

Return counts for specific mailbox folders

Cheap targeted count refresh for folders you already know. Pass folder_ids from list_folders/create_folder and receive the same folder objects with total_emails and unread_emails. On IMAP/Gmail this avoids a full mailbox LIST plus STATUS for every label.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get-attachment

Get /ops/get-attachment | Auth: Read

Download a single attachment’s bytes (base64)

Downloads one attachment’s raw bytes, base64-encoded for JSON transport. The part_id comes from a get-message response’s attachments[].part_id. Works on both backends — the platform Stalwart (JMAP blob download) and external IMAP (spec.mailbox_backend=“imap”; the part is pulled from the message’s MIME tree). message_id is the IMAP UID on the IMAP backend. To reconstruct the file, base64-decode data_base64 (its decoded length equals size).

get-message

Get /ops/get-message | Auth: Read

Get a single email message with full body

Retrieves the full message including text and HTML body, headers, and attachment metadata. On the platform Stalwart (JMAP) backend the message is automatically marked as read. On the external IMAP backend (spec.mailbox_backend=“imap” / spec.imap_host set) the body is fetched with BODY.PEEK so retrieval does NOT implicitly set the Seen flag — use mark-read explicitly. message_id is the IMAP UID on the IMAP backend.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list-addresses

Get /ops/list-addresses | Auth: Read

List all email addresses for this circle

Returns all provisioned email addresses/aliases for this circle’s mail account, including the primary address.

list-events

Get /ops/list-events | Auth: Read

Read the per-circle email audit log: send/open/click/bounce/suppress/unsuppress/consent/campaign events.

This is the email-domain audit trail. Filter by event_type (sent, opened, clicked, bounced, suppressed, unsuppressed, consent_changed, campaign_started, campaign_finished) or by address to drill into one recipient’s history. Includes parsed bounce diagnostics (status_code, severity, failed_recipient) in details for bounced rows.

list-inbox

Get /ops/list-inbox | Auth: Read

List email messages in a folder

Lists messages in the specified folder (default: INBOX). Backend is chosen from spec: the platform Stalwart mailbox via JMAP (default), or an external IMAP server when spec.mailbox_backend=“imap” / spec.imap_host is set (read creds: spec.imap_credential_ref JSON {username,password} → else inline spec.imap_username + spec.imap_password, app-password only). Paginated with page_token for cursor-based navigation (a UID cursor on the IMAP backend). Returns message envelopes (id, from, subject, date, read status) without bodies.

list-suppressions

Get /ops/list-suppressions | Auth: Read

List suppressed email addresses for this circle (per-circle deliverability protection list).

Use this to verify the bounce auto-clean is keeping a clean list. Shows address, reason, source, notes, and when each entry was created.

list_domains

Post /ops/list_domains | Auth: Read

List custom sending domains registered to this circle

Each entry carries verified so callers know which domains are eligible to be used as spec.from_address.

list_folders

Post /ops/list_folders | Auth: Read

List JMAP mailboxes (Inbox, Sent, custom folders)

Returns every folder in the mailbox: Inbox, Sent, Drafts, Trash, Junk, and any user-created folders. Each entry has id, name, role (inbox/sent/etc.), parent_id (for nested folders), total_emails, and unread_emails. Use the id to target move-to-folder.

list_outbox

Post /ops/list_outbox | Auth: Read

List drafted outbound dispatches in the outbox queue

Returns email-outbox rows for THIS element. Filter by status to scope the listing — defaults to pending so operators see only the queue currently awaiting approval. Each row includes the draft payload so a reviewer can inspect what would be sent before approving.

mark-read

Post /ops/mark-read | Auth: Write

Mark a message as read

Sets the $seen JMAP keyword on the specified message.

move_to_folder

Post /ops/move_to_folder | Auth: Write

Move a message to one or more folders

Updates the message’s mailboxIds via Email/set. Pass folder_id (single string) for an exclusive move, or folder_ids (array) to file the message into multiple folders simultaneously — JMAP allows a message to live in any number of mailboxes.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

provision-address

Post /ops/provision-address | Auth: Write

Add an additional email address to this circle

Provisions a new email address/alias on the mail server for this circle. Only triform.wtf, triform.dev, and triform.cloud domains are allowed. External domains (gmail.com, outlook.com, etc.) will be rejected. Idempotent (BUGS-476): re-calling for an already-provisioned address returns 200 with provisioned:false, already_exists:true instead of 500. Setup scripts can safely re-run without a check-before-provision prelude.

rate-status

Get /ops/rate-status | Auth: Read

Read the current daily send-rate counter for this circle and the configured cap.

Use this to verify the rate guard is honest about how many sends remain today. limit is the per-day cap (default 500, env EMAIL_DAILY_CAP_PER_CIRCLE override); remaining is limit minus the in-process counter for the current UTC day; reset_at is the next UTC midnight.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

receive

Post /ops/receive | Auth: None

Receive incoming external traffic

Entry point for external traffic reaching this IO element. Declared auth: none to bypass platform auth — element-level auth is enforced by IoReceiveExecutor before dispatching into the flow graph. The flow/app that wires this element as an entry point determines what happens next.

reject_dispatch

Post /ops/reject_dispatch | Auth: Write

Reject a queued draft without sending

Transitions an outbox row from pending → rejected and records an optional reason for audit. The draft is not dispatched. Idempotent against the row’s state machine — repeat rejection returns EMAIL_OUTBOX_INVALID_STATE if the row already moved past pending.

remove-address

Post /ops/remove-address | Auth: Write

Remove an additional email address from this circle

Removes an email alias from the mail server. Cannot remove the primary circle address (the default username@domain address).

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

remove-suppression

Post /ops/remove-suppression | Auth: Admin

Manually remove an address from this circle’s suppression list. Audit-sensitive: reason is required.

DANGER: removing a suppression re-permits mail to an address that has been blocked. Provide a reason so the audit trail is honest. Emits an UNSUPPRESSED audit event.

remove_domain

Post /ops/remove_domain | Auth: Write

Drop a custom sending domain from the registry

Sends from this domain immediately fall back to the platform mailbox. Reversible only by re-running add-domain + verify-domain.

remove_label

Post /ops/remove_label | Auth: Write

Remove a label keyword from a message

Clears a previously-applied keyword. Idempotent — clearing a label that wasn’t set is a no-op.

reply

Post /ops/reply | Auth: Write

Reply to a received email

Convenience operation for replying to an inbound email. Automatically sets In-Reply-To, References, and the To address from the original message. The subject is prefixed with “Re: “ if not already present.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

search

Get /ops/search | Auth: Read

Search email messages

Full-text search across message subjects, bodies, and sender addresses. Uses JMAP Email/query with text filter on the platform Stalwart backend, or IMAP UID SEARCH TEXT when spec.mailbox_backend=“imap” / spec.imap_host is set. Optional structured filters narrow the result: from (sender substring/address → IMAP SEARCH FROM / JMAP filter.from), since (received on/after, YYYY-MM-DD → IMAP SINCE / JMAP after), and before (received strictly before, YYYY-MM-DD → IMAP BEFORE / JMAP before). On the IMAP backend an unset folder searches All Mail (the RFC 6154 \All folder) when the account exposes one, otherwise INBOX; pass an explicit folder to scope. query may be empty when at least one structured filter is set. Returns matching message envelopes sorted by date descending.

send

Post /ops/send | Auth: Write

Send an email

Composes and sends an email via SMTP submission. Requires spec.credential_ref and spec.from_address (or spec.sandbox_managed=true via the platform mailbox). Send-side SMTP credential precedence: spec.credential_ref (secret element holding JSON {username,password}) → else inline spec.smtp_username + spec.smtp_password (app-password). When mailbox_backend=“imap” / imap_host is set, mail still leaves via spec.smtp_host with these same SMTP credentials — IMAP is read-only; sending is always SMTP. App-password only (no OAuth). Recipients (to / cc / bcc) accept either a single email string or an array of email strings — both shapes succeed (BUGS-467). Supports plain text and HTML (multipart/alternative). If input.in_reply_to is set, adds In-Reply-To and References headers for threading. DKIM signing is handled automatically by the platform mail server. Refuses the send when spec.from_address points at a domain this circle does not own + verify: 403 EMAIL_DOMAIN_OWNED_BY_OTHER_CIRCLE (cross-circle), 412 EMAIL_DOMAIN_NOT_VERIFIED (own domain, verification pending), or 412 EMAIL_DOMAIN_NOT_REGISTERED (no add_domain call for the domain). Unset spec.from_address (or use ops/bootstrap_managed_domain) to dispatch from the platform mailbox.

send_tracked

Post /ops/send_tracked | Auth: Write

Campaign-style send with consent gate, open/click tracking, and audit trail

Single-recipient send for outreach campaigns. Same compliance gates as send (suppression, rate limit, List-Unsubscribe header, audit log) plus a consent check: contact must have consent_status of soft_optin or double_optin in the data/contacts element, otherwise the send is refused with EMAIL_NO_CONSENT. The HTML body is rewritten to inject an open-tracking pixel and link-redirects, and a row is reserved in email_sends so the public /t/open/:id and /t/click/:id endpoints can record hits. Per-recipient tokens — wrap in a loop element to send to multiple contacts.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

test_connection

Post /ops/test-connection | Auth: Execute

Test SMTP connection and authentication

Connects to the configured SMTP server, performs EHLO and authentication. Returns the server capabilities and authentication status. Does not send any email.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

unread-count

Get /ops/unread-count | Auth: Read

Get unread message count

Returns the number of unread messages in the inbox.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

verify_domain

Post /ops/verify_domain | Auth: Write

Run DNS TXT lookup and flip the domain to verified on success

Re-run after publishing the verification TXT record from add-domain. Returns the verified status. Failures include the lookup error so the operator can debug DNS propagation.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
EMAIL_AUTH_FAILED	auth	no	SMTP authentication failed (invalid credentials)
EMAIL_SEND_FAILED	internal	yes	Failed to send email via SMTP
EMAIL_INVALID_ADDRESS	validation	no	One or more recipient addresses are invalid
EMAIL_REJECTED	internal	no	Remote server rejected the message (permanent failure)
EMAIL_RATE_LIMITED	internal	yes	SMTP rate limit exceeded
EMAIL_TOO_LARGE	validation	no	Message exceeds maximum size limit
EMAIL_CREDENTIAL_MISSING	auth	no	credential_ref not set or referenced secret not found
EMAIL_INVALID_DOMAIN	validation	no	Email domain not allowed — only triform.wtf, triform.dev, triform.cloud permitted
EMAIL_ALIAS_EXISTS	validation	no	Email alias already exists on this account