Cookbook

EmailConnection API

← Back to Documentation Hub

EmailConnection sends outbound emails with plain text, HTML bodies, and file attachments from a pipeline. It supports both static YAML configuration and upstream table-driven messages.

Connection Header

kind: CustomConnection
locator: EmailConnection

Modes of Operation

Mode (kind) Behavior
sink (Primary) Sends an email. Reads the message payload either from params.message in YAML or from a message JSON column in the upstream table.
tap (Stage / Preview) Validates the message parameters and outputs a single-row table with a message (JSON) column without sending an email—useful for inspecting or transforming payloads before delivery.

Inputs (params)

When used as a sink, wrap the email fields under params.message (or omit params.message to read from the upstream step's message column). When used as a tap, place the fields directly under params.

Parameter Type Required Default Description
sender string Yes — Verified sender email address (e.g., [email protected]).
recipients list[string] Yes — Primary recipient email addresses (To).
cc list[string] No [] Carbon-copy recipient email addresses.
bcc list[string] No [] Blind carbon-copy recipient email addresses.
subject string Yes — Email subject line. Supports <<...>> dynamic expressions.
text string Conditional* — Plain-text email body.
html string Conditional* — HTML email body.
attachments list[object] No None List of file attachment objects (see schema below).
broadcast boolean No False When True, sends individual emails per recipient rather than a single grouped message.
transport string No "ses" Outbound mail transport backend (configured via workspace environment credentials).

*Provide at least one of text or html.

Attachment Object Schema

Each entry in attachments accepts the following keys:

Key Type Required Default Description
content bytes / base64 Yes — File content, typically referenced from an upstream variable (<<variables.look('...')>>).
name string Yes — Filename shown to the recipient (e.g., report.xlsx).
mime string No None MIME content type (e.g., application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).
is_inline boolean No False Set to True to embed the attachment inline in an html body.
cid string No None Content-ID used to reference inline assets (<img src="cid:...">).

Outputs

  • sink mode: Dispatches the email via the configured transport and logs Email '<subject>' sent to <recipients>. Raises a pipeline error if delivery fails.
  • tap mode: Produces a 1-row table containing:
Column Type Description
message JSON Serialized EmailMessage payload ready to be passed to a downstream EmailConnection sink.

Building Rich HTML Bodies from Pipeline Variables

If an upstream step exposes data via a Variable sink (at the pipeline author's discretion), you can reference those values inside the html field to render structured summaries or HTML tables directly in the email body—either alongside an attachment or in place of one:

- name: SendEmail
  kind: sink
  connection:
    kind: CustomConnection
    locator: EmailConnection
    classname: EmailConnection
    module: buimatic.flow.modules
    params:
      message:
        sender: [email protected]
        recipients:
          - [email protected]
        subject: "Daily Summary: <<variables.look('SummaryData[0].title')>>"
        html: |
          <p>Here are today's key figures:</p>
          <table border="1" cellpadding="6" cellspacing="0">
            <thead>
              <tr>
                <th>Metric</th>
                <th>Value</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>Critical Items</td>
                <td><<variables.look('SummaryData[0].critical_count')>></td>
              </tr>
            </tbody>
          </table>

Minimal Examples

1. Direct Sink with Attachment

- name: SendEmail
  kind: sink
  connection:
    kind: CustomConnection
    locator: EmailConnection
    classname: EmailConnection
    module: buimatic.flow.modules
    params:
      message:
        sender: [email protected]
        recipients:
          - [email protected]
        subject: "Weekly Report"
        text: "Please find the attached spreadsheet."
        attachments:
          - content: <<variables.look('ReportExport[0].base64_output')>>
            name: report.xlsx
            mime: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

2. Table-Driven Sink (via Upstream message Column)

When a preceding tap or SQL transform builds a message JSON column, omit params.message on the sink:

- name: SendPreparedEmails
  kind: sink
  connection:
    kind: CustomConnection
    locator: EmailConnection
    classname: EmailConnection
    module: buimatic.flow.modules
    params:
      transport: ses

← Back to Documentation Hub