Make the email body format explicit instead of guessing it from strings
Stacked on twentyhq/twenty#30453.
Problem
An email body string meant three things (a serialized document, HTML or plain text), and every layer decided which by inspecting it with parseJson and looksLikeHtml. So 20 < 50 or a stray & could change how a body was read and sent. The same guessing ran at every entry point: the email tools, proposals, the sendEmail mutation, the app channel send, workflow steps and the workflow editor.
Change
Explicit format, at the agent and app edge only. send_email, draft_email and propose_tool_call take an EmailBodyInput (twenty-shared), discriminated by type:
type EmailBodyInput =
| EmailDocument // { type: 'doc', content: [...] }
| { type: 'html'; html: string } // sent as written: one htmlDocument block
| { type: 'text'; text: string }; // paragraphs, \n → hard breaks
A bare string is rejected by the schema, and the tool description names the three shapes. convertEmailBodyInputToEmailDocument is the one conversion; the tools and buildEmailProposal call it. The dev seeder's proposed emails send { type: 'html' }.
Internal APIs only see documents, validated once:
composeEmailis the one place that validates an outbound document (parseEmailDocumentOrThrow), since approved tool calls reach the tools without schema validation. ThesendEmailmutation only decodes the JSON; the app channel send parses it the same way. Anything else isINVALID_EMAIL_BODY.- One rule for versions: a document without
attrs.schemaVersionis version 1 everywhere (tools, workflows, both mutations, the workflow editor). - Workflow steps:
resolveInputresolves variables inside the stored document (so step logs, including failed ones, show the values used), and atoToolInputhook onToolBackedWorkflowActionparses it for the tool.workflowSendEmailActionSettingsSchemaenforces what its description says, so a non-document body fails when the step is saved, not when it runs;validateWorkflowStepParamsrelies on it instead of its own check. - Empty bodies are documents too. New send/draft email steps are created with an empty email document instead of
'', and the editor form saves one when a step has none. The2-59workspace commandbackfill-empty-workflow-email-bodiesstores it in existing steps whose body is a blank string, so nothing special-cases''any more. A step with no body at all (the field is optional) sends the empty document. - The composer starts from a serialized empty document instead of
''.
looksLikeHtml leaves runtime code. It and the string-sniffing converter (convertEmailBodyToEmailDocument, convertStringBodyToEmailDocument, HTML_ELEMENT_NAMES) move unchanged into upgrade-version-command/2-47/utils/. The 2-47 workflow-body command is now their only user, as UPGRADE_COMMANDS.md asks for legacy formats only a command needs.
Breaking, accepted (no deprecation window)
- Agents and apps must send
{ type: 'text' | 'html', … }or a document tosend_email,draft_emailandpropose_tool_call. A matching Twenty for Twenty change (twentyhq/twenty-eng#760) sends{ type: 'text', text }; ship them together. - The
sendEmailandsendAppChannelMessageGraphQL mutations reject HTML and plain-text string bodies:bodymust be a serialized email document. The app docs (messaging-channels.mdx,inbox.mdx) now state this. - Workflow steps whose stored body is still an HTML or plain-text string (only possible for steps written outside the editor after 2-47 converted existing ones) fail with
Invalid email document. - Rollout: until the 2-59 backfill reaches a workspace, a step with a blank stored body fails instead of sending an empty email. No fence: only steps that would send an empty body are affected, for that window.
Needs
ci:allow-previous-version-upgrade-mutationlabel. The move adds files under2-47/and rewires that command's import, which the upgrade mutation guard blocks by default. Command behaviour is unchanged: same code, now command-local.
Follow-up (not here)
- Sending
bodyas a JSON scalar on thesendEmailand app channel mutations, instead of a stringified document, needs GraphQL codegen against a running server.
Tests
- Shared: the converter (text with CRLF and literal
</&/{{…}}, HTML as written, a document stamped with its version), the schema rejecting a bare string or unknown type, and step validation accepting a document with or without a version and rejecting empty, HTML and text bodies. - Server:
resolveEmailBodyowns the parsing cases (strict parse, whole-body variable holding HTML or a document, rejection of blank and string bodies); the send and draft workflow actions (no body sends the empty document, an invalid body never reaches the tool, a failed draft logs the resolved body); the tool composing from the converted document; proposals with{ type: 'text' }and a rejected bare string; the dev seeder's proposals resolving. The 2-47 converter spec moves with the code. - Front: the workflow body editor opening an unversioned document and not reading an HTML string.
- Integration (
outbound-email-body-formats): explicit tool bodies; one stored string body failing its step; whole-body variables as documents; the mutation accepting an unversioned document and rejecting a non-document; the 2-59 backfill (dry run, then both copies hold the empty document and the step sends).
Generated by Claude Code