Skip to main content

Start a Process by Email

Any Softyflow process can be started by an email. When a message arrives at the address of a process, Softyflow starts a new instance of that process and gives it the content of the message as variables: subject, sender, text body, HTML body and attachments. The rest of the flow uses them like any other process variable.

Nothing has to be configured in the process: there is no special start event to set. The process only needs to be published in the environment the email targets.

1. The Address of a ProcessDirect link to 1. The Address of a Process

Each process has one address per environment:

<instance>+<processId>.<mode>@m.softyflow.io
PartValue
<instance>The name of your Softyflow instance: acme for https://acme.softyflow.io.
<processId>The ID of the process: the last part of its URL in the IDE (/ide/process/<processId>).
<mode>The environment of the new instance: test, uat or prod. Without .<mode>, the instance starts in prod.

For example, acme+6aeca4b1c2d3e4f5a6b7c8d9.test@m.softyflow.io starts the process 6aeca4b1c2d3e4f5a6b7c8d9 of the instance acme in TEST.

tip

To start a process from a mailbox of your company (invoices@your-company.com), forward that mailbox to the address of the process with a rule of your mail server.

info

The start by email uses the Softyflow receiving domain m.softyflow.io. It is available on instances hosted at <instance>.softyflow.io. For another hosting, contact Softyflow to set up the receiving domain.

2. The Variables of the InstanceDirect link to 2. The Variables of the Instance

The new instance receives these variables:

VariableTypeContent
subjectstringThe subject of the email.
contentstringThe text body, without the quoted replies and the signature.
mailBodyPlainstringThe full text body, quoted replies and signature included.
contentHtmlstringThe HTML body, without the quoted replies and the signature. null when the email has no HTML part.
mailBodyHtmlstringThe full HTML body. null when the email has no HTML part.
fromstringThe From header as written by the sender, for example Jane Doe <jane@client.com>.
senderstringThe address of the sender only: jane@client.com.
recipientstringThe address the email was sent to: the address of the process.
filesarrayThe attachments (see Attachments). An empty array when there are none.
startedAtnumberThe time of reception, in milliseconds since 1970 (epoch).
SF_modestringtest, uat or prod, from the address.
SF_initiatorobject{ mail: 'Auto', firstName: 'Auto' }: an instance started by email has no user as its initiator.

The text and HTML bodies come in two versions. Use content or contentHtml to work on what the sender wrote, and mailBodyPlain or mailBodyHtml to keep the whole message, for example to archive it or to show it as it was received.

The HTML is kept as the sender's mail program wrote it. Images pasted in the message are cid: references in the HTML; the images themselves are in files.

caution

The HTML of an email comes from outside your company. Do not insert it as is into a page shown to your users: show it in an isolated frame, or clean it first.

3. AttachmentsDirect link to 3. Attachments

Each attachment is stored in the files of your Softyflow instance as soon as the email arrives. The files variable lists them:

[
  {
    _id: "6aecb0f1c2d3e4f5a6b7c8d9",   // the ID of the stored file
    filename: "invoice-2026-11.pdf",
    contentType: "application/pdf",
    length: 48213,                    // size in bytes
    chunkSize: 261120,
    uploadDate: "2026-11-19T09:12:03.000Z"
  }
]

Read an attachment in a script with the File SDK:

const pdf = files.find(f => f.contentType === "application/pdf");
if (!pdf) return null;
const buffer = await SF.file.getFileBufferById(pdf._id);

4. Where the Email Is StoredDirect link to 4. Where the Email Is Stored

An email that starts a process is kept in two places:

  • In the instance: the variables of section 2 are variables of the instance, like those of a form. They are visible in the instance and stay with it.
  • In the files: the attachments, as described in section 3.

Softyflow also keeps a copy of each email received (subject, addresses, text and HTML bodies, attachment list) for its own records. To use the emails in your application, for example in a report or a table, save what you need in a collection of your project with a script of the first step:

await SF.collection.insertOne("received-emails", {
  subject,
  sender,
  receivedAt: new Date(startedAt),
  text: content,
  html: contentHtml,
  attachments: files.map(f => ({ _id: f._id, filename: f.filename }))
});
return true;

5. Using the Email in the FlowDirect link to 5. Using the Email in the Flow

The variables are available in every step, like any process variable:

  • Assign a task to the sender, or to a role chosen from the subject or the address.
  • Reply with a send task: put sender as the recipient and subject in the subject of the email.
  • Decide with a gateway, for example subject.toLowerCase().includes("urgent").
  • Extract data from the body in a script, for example an invoice number from content.

6. TestingDirect link to 6. Testing

Send an email to the test address of the process, then open the new instance in the instance tracking to check its variables.

In TEST, Softyflow sends every email of an instance to its initiator and adds the initiator to every task, so that a tester receives everything. An instance started by email has no initiator (Auto), so its TEST emails and tasks reach nobody. To test the whole flow, make the TEST runs act as a real user: add on the first step a script variable named SF_initiator that, in TEST only, returns that user:

// TEST only: the run acts as the tester. UAT and PROD keep 'Auto'.
if (SF_mode !== "test") return SF_initiator;
const user = await SF.user.getUserByMail("tester@your-company.com");
if (!user) return SF_initiator;
const roles = [...(user.group_test || []).map(String), "public", "everybody"];
return {
  _id: String(user._id),
  fullName: [user.firstName, user.lastName].filter(Boolean).join(" "),
  firstName: user.firstName || "",
  lastName: user.lastName || "",
  mail: user.email,
  roles,
  modeGroups: { test: roles }
};

In UAT and PROD, the emails and tasks of the instance go to their real recipients.

7. TroubleshootingDirect link to 7. Troubleshooting

SymptomCause
No instance startsThe address is wrong (instance name, process ID), or the process is not published in the environment of the address.
contentHtml and mailBodyHtml are nullThe email was sent as plain text only. Use content or mailBodyPlain.
content is empty but mailBodyPlain is notThe whole message was detected as a quoted reply or a signature. Use mailBodyPlain.
Images are missing from the HTMLPasted images are cid: references: the images are in files.
Nobody receives the TEST emailsThe initiator of the instance is Auto: see Testing.