Email ingestion
Save emails and their attachments from the workspace's own Mailbox or a Microsoft 365 or Gmail mailbox into SPARK, as records and files a workflow can work on.
A lot of investment operations still arrives by email: a daily NAV pack from an administrator, a trade confirmation, a statement from a custodian. The Save Emails action brings those emails into SPARK. Each run reads one mailbox, saves every matching email as a record of a data object, and saves each attachment in Files, linked to its email. From there the rest of the workflow, or a file-triggered one, can read the attachments like any other file.
Before you start: pick a mailbox to read
The step reads one of two kinds of mailbox:
- The workspace's own Mailbox, the address SPARK receives email at. Turn it on in Settings › Extensions › Mailbox and give its address to whoever sends you the emails. See Mailbox. The Mailbox ships with the next release.
- A Microsoft 365 or Gmail mailbox, connected in a shared vault. Activate the Microsoft 365 or Gmail connector (see Connectors), then connect the mailbox's account in a shared vault (see Connect an account and Vaults). A workflow never reads a personal vault's connection, even yours.
The step only reads the mailbox: no email is marked read, labelled or moved.
The Mailbox can make this workflow for you: its Create workflow adds a draft called Save emails sent to the Mailbox, a Schedule Trigger followed by Save Emails. Activate it, then give it a schedule in Workflows › Schedulers. See Mailbox.
Add the step
- Open the workflow on the canvas. A Manual or Schedule trigger is the usual start, so the mailbox is read on demand or on a timer. See Scheduling.
- In the Configure tab, type Save Emails in the Search actions... box, or find it in the Data group, and click it.
- In the side panel, pick the Mailbox first, then narrow which emails to save.
- Save the workflow.
Pick the mailbox
The Mailbox list starts with This workspace, the workspace's own Mailbox while it is on, as Mailbox and its address. Then come the Microsoft 365 and Gmail connections in each shared vault, under the vault's name, each as the connector and the account, for example Microsoft 365 · ops@kestrel-capital.com. With nothing to pick, the field says No connection to pick yet. Connect one in a shared vault. A step saved on a connection that is no longer in a shared vault keeps it, greyed, under Not in a shared vault, and one saved on the Mailbox while it is off reads Mailbox (off).
Choose which emails to save
| Field | What it does |
|---|---|
| Data object | The data object the emails are saved in, by name. Leave it empty to use the mailbox's own (see below) |
| Folder | The mail folder (Outlook) or label (Gmail) to read. Empty reads the Inbox. The Mailbox has no folders: leave it empty |
| From | Only emails from this address (nav@fabrikam.com) or this domain (fabrikam.com) |
| Subject contains | Only emails whose subject contains this text, in any case |
| Received | From and To: the days the emails arrived, in UTC, both included. A Date context variable can set them at each run |
| Only emails with attachments | Skips emails whose only attachments are images inside the text |
| Max emails | How many emails to save at most, newest first, from 1 to 100. Defaults to 25. Emails already saved do not count |
| Save attachments | On by default. Saves each attachment in Files, linked to its email, when SPARK accepts its type |
| Skip emails already saved | On by default. Skips an email the data object already holds. Off, its record is archived and the email is saved again with its attachments |
| Labels | File labels every saved attachment gets, by name. A name the workspace has no label for is left off |
A run reads through at most 1,000 emails, matching or not, before it stops. If there is more to save than Max emails allows, rerun the step: emails already saved are skipped, so each run picks up where the last one stopped.
Try the settings with a dry run
At the foot of the panel, the Dry run card shows what a run would save with the settings as they are: Lists the emails a run would save with these settings, and saves nothing. Click Run on the card. It reads the mailbox for up to a minute, saves nothing and changes no email, then lists the emails a run would take, newest first, under Subject, From, Received and Attachments, with the data object they would go to beside Dry run.
The line above the list says how many there are, for example 3 to save · 1 already saved. Nothing was saved. It can add:
- Stopped after a minute: a run looks further.
- More emails match than one run takes.
- The first run makes this data object.
With nothing to save, the card reads No emails to save. Until a mailbox is picked, it says Pick the mailbox first. A setting read from a context variable has no value outside a run, so the card says which it shows without. Change a setting and the answer clears: run it again.
Where the emails land
Unless you name a Data object, each mailbox gets a data object of its own, named after its service and address:
- Emails - Mailbox for the workspace's Mailbox, which keeps that name when the Mailbox's address is rotated
- Emails - Outlook (ops@contoso.com) for a Microsoft 365 mailbox
- Emails - Gmail (ops@contoso.com) for a Gmail mailbox
SPARK creates it from the Email template on the first run and files it in a data object group called Email Ingestion, so you can tell at a glance which connection fed which emails. A name you give in Data object wins, and an object that already exists keeps its group.
Each email is one record with these columns:
| Column | Holds |
|---|---|
| Subject | The email's subject |
| From and From address | The sender's name and address, and the address alone to filter by |
| To and Cc | Who it was sent and copied to |
| Received | When it arrived in the mailbox |
| Body | The email's text |
| Attachments | Its attachments, saved in Files |
| Attachments not saved | Each attachment left out, and why: an image inside the text, or a type SPARK does not accept |
| Connector, Account and Folder | Where it was read from |
| Link | Where the email opens in its mailbox |
| Message ID and Key | The email's Internet Message-ID, and the key SPARK uses to recognize an email it already saved |
The key combines the Message-ID, the sender and the arrival time, so rerunning over the same days saves nothing twice, and a different email cannot pass for one already saved.
What the step passes on
The step's output is a table with one row per email it saved: subject, from, received, the names of its attachments, and the record's id. In a run, the step's output also links every file it saved, so you can open an attachment straight from the run.
To act on the attachments, either:
- add steps after Save Emails in the same workflow, or
- build a separate workflow with a File Received trigger that matches the attachments, by name, extension or label. See File-triggered workflows.
Agents read mail the same way
An agent with the Microsoft 365 or Gmail connector, or with the Mailbox's tools, can save emails too, with the same code and the same rules: the same per-mailbox data object, the same Email Ingestion group, the same skipping of emails already saved. A workflow is the better choice when it should happen on a schedule, every day, without anyone asking.
About the Email Received trigger
The action list's Trigger group includes Email Received, dimmed, with the hint This action is disabled in this workspace. It does not start runs yet. To react to new mail, schedule a workflow that starts with Save Emails instead, such as the one the Mailbox's Create workflow makes.
Where to go next
- Mailbox
- File-triggered workflows
- Scheduling
- Ask an agent, to read what an email says
- Read documents
- Vaults