Transform Steps

Table of contents

  1. html_to_text
  2. remove_fields
  3. replace_values
  4. strip_attachments_if

Transform steps run before the final map.* step and return a modified message for later steps. Use them to normalize HTML, redact fields, rewrite values, or drop attachments before the payload is mapped.

Use the MailWebhook agent skill to choose and configure transform steps for your pipeline. Include a sample email and describe the fields or attachments you want to normalize, change, or remove.

Built-in non-terminal steps:

StepUse it for
html_to_textConvert message HTML into deterministic plain text.
remove_fieldsRemove or clear selected message fields before mapping.
replace_valuesSet subject, body, or header values from literals or small templates.
strip_attachments_ifRemove attachments that match configured MIME, size, and filename conditions.

html_to_text

html_to_text writes deterministic text to message.text from message.html. If the message has no HTML, the step leaves the message unchanged.

Arguments:

ArgDefaultDescription
prefer"html"Accepted values are "html" and "text". The current step converts HTML when HTML is present.
width80Soft wrap column. Use 0 to disable wrapping.
preserve_linkstrueRender anchors as text (url) when possible.
collapse_whitespacetrueCollapse runs of whitespace into single spaces.
keep_tablesfalseRender HTML table cells as TSV-like rows instead of linearized text.

Example:

{
  "name": "html_to_text",
  "args": {
    "width": 0,
    "preserve_links": true,
    "keep_tables": true
  }
}

Use width: 0 when downstream systems should receive unwrapped text. Use keep_tables: true when table-like text should remain row-oriented before a mapper runs.

remove_fields

remove_fields clears message fields, removes headers, removes all attachments, or clears selected attachment metadata fields.

Arguments:

ArgDefaultDescription
pathsrequiredArray of field paths to remove or clear.

Supported paths:

  • subject
  • text
  • html
  • headers.<lowercase-key>
  • attachments
  • attachments[*].filename
  • attachments[*].content_type
  • attachments[*].size
  • attachments[*].sha256

Example:

{
  "name": "remove_fields",
  "args": {
    "paths": [
      "headers.received",
      "html",
      "attachments[*].sha256"
    ]
  }
}

Unknown attachment subfields are ignored. Attachment field removal clears safe metadata fields while preserving attachment identity. Internal attachment storage fields are not part of the public transform contract.

replace_values

replace_values assigns literal or templated values to supported message fields. String values can include `` placeholders.

Arguments:

ArgDefaultDescription
setrequiredObject mapping writable paths to literal or templated values.

Supported writable paths:

  • subject
  • text
  • html
  • headers.<lowercase-key>

Supported template paths:

  • subject, text, html
  • headers.<lowercase-key>
  • from[<index>].email, from[<index>].name
  • to[<index>].email, to[<index>].name
  • ctx.route_id, ctx.project_id, ctx.source_type, ctx.raw_size_bytes

Example:

{
  "name": "replace_values",
  "args": {
    "set": {
      "subject": "Order ",
      "headers.x-route": ""
    }
  }
}

Unresolved placeholders are left unchanged.

strip_attachments_if

strip_attachments_if removes attachments that satisfy all supplied conditions. Provide at least one condition.

Arguments:

ArgDefaultDescription
mime_in[]MIME glob patterns such as "image/*" or "application/pdf".
max_size_kbnoneRemove attachments larger than this size.
filename_regexnoneRemove attachments whose filename matches this regex. Unsafe regexes are rejected.

Example:

{
  "name": "strip_attachments_if",
  "args": {
    "mime_in": ["application/octet-stream"],
    "max_size_kb": 1024,
    "filename_regex": "(?i)\\.(exe|scr)$"
  }
}

When multiple conditions are provided, an attachment must match all of them to be removed.