Skip to main content

Core Concepts

Before building your first workflow, it helps to understand how Email2AT is structured and how it processes email. This page covers the mental model behind the system: the hierarchy of components, how they relate, and the key behaviors that govern everything.

The Processing Hierarchy​

When an email arrives, Email2AT processes it through four levels:

Domain
  └── Mailbox
        └── Rule(s)
              └── Action Step(s)

Domain​

Every inbound email domain belongs to one account. This includes hosted subdomains (e.g., your-company.onmspi.net) and custom domains you point to Email2AT with an MX record. When an email arrives, Email2AT matches the domain to your account and begins looking for a mailbox.

Set up your first domain → Create Your First Mailbox

Mailbox​

A mailbox is a specific email address within a domain (e.g., [email protected]). When Email2AT receives an email, it looks up the matching mailbox and processes the rules attached to it. A mailbox with no rules accepts and logs inbound emails but takes no action. This is useful for capturing emails while you are still building the rule.

Rules​

A rule is a named container for one or more action steps. Rules attached to a mailbox are evaluated top-to-bottom in order. Every rule that matches fires (not just the first one) unless a Stop action halts processing.

Each rule has an optional Expression that controls whether it fires at all. If the expression is empty, the rule fires for every email. If an expression is set, the rule only fires when the expression is true.

Learn more about Expressions → Expression Builder

Action Steps​

Inside each rule, action steps execute top-to-bottom in order. Each step can also have its own optional expression ("only run if..."), so you can make individual steps conditional.

The output of each step is stored in a named variable and is available to all subsequent steps in the same rule. This is what allows you to build multi-step workflows: look something up in one step and use the result in the next.

How Rules and Steps Stop​

By default, every matching rule fires, and every step within a rule runs. To stop processing early, use a Stop action:

Stop actionEffect
Stop Processing This RuleStops remaining steps in the current rule. Other matching rules continue.
Stop Processing This Message CompletelyHard stop. No further rules or steps run for this email.

Most workflows end with a Stop action. For example, after creating a ticket, you stop so that no further rules accidentally create a second ticket for the same email.

The most common mistake

Forgetting to add a Stop action. Without it, every matching rule fires. In a standard support mailbox with an Update rule and a Create rule, if the Update rule succeeds but does not stop, the Create rule will also run and create a second ticket.

Variables and Data Flow​

Every action step can store its results in a named variable using the Store results in variable field. The variable is then accessible in all subsequent steps using {{custom.variableName}}.

Email variables​

In addition to variables you create, all inbound email data is available from the start of every rule:

VariableDescription
{{email.subject}}Subject line
{{email.from.address}}Sender's email address
{{email.from.display}}Sender's display name
{{email.body}}Full email body (plain text preferred; falls back to HTML conversion)
{{email.body_stripped.visible}}Body with quoted replies and signature removed. Safe to use; always has a value.
{{email.body_stripped.signature}}Extracted signature section
{{email.body_stripped.quoted}}Extracted quoted-reply section
{{email.mailbox}}The email address the message was received at
{{email.to.[0].address}}First recipient's address (increment index for additional recipients)
{{email.cc.[0].address}}First CC recipient's address
The { shortcut

In any text field inside an action step, type { to open the variable autocomplete menu. Every available variable (email properties, metadata, and anything stored in previous steps) appears in the list.

Chaining steps​

The output of each step accumulates as the rule processes. Step 3 can reference variables set by steps 1 and 2. Step 5 can reference all of them. Nothing is lost as the rule progresses, so you can always reach back to an earlier result.

Inspecting variables in the processing log​

The History page shows the complete execution log for every processed email. For each step, you can see the exact state of every custom.* variable, both before and after the step runs. This makes it straightforward to understand exactly what data is available at each point in the workflow.

Workflow Actions vs. API Call Actions​

Email2AT provides two categories of actions for working with Autotask:

Workflow actions​

Workflow actions contain built-in business logic and perform multiple API calls behind the scenes. They accept high-level inputs (like an email address) and handle the full lookup-and-create process automatically.

Examples:

  • Create Autotask Ticket: searches for the sender as a Contact, finds the Account, creates the ticket, and attaches files
  • Update Existing Autotask Ticket: scans the email for a ticket number, finds the ticket, adds a note, and updates the status
  • Create Autotask Ticket (by Configuration Item): extracts a device identifier from the email, finds the matching CI, and creates the ticket under the CI's account

Use workflow actions when you are processing standard incoming email and want Email2AT to handle the matching and routing logic for you.

API call actions​

API call actions make a single, direct call to the Autotask API. You provide all the parameters. No additional lookup logic is included.

Examples:

  • API: Create an Object: creates any Autotask entity with the exact fields you specify
  • API: Update an Object: updates any entity by ID
  • API: Query for One Object: searches Autotask and returns the top result
  • API: Query for Object(s): searches Autotask and returns an array of results

Use API call actions when you already have all the required IDs (from a previous step), when you need to work with entity types not covered by workflow actions, or when you are building custom multi-step logic.

Choosing between them: Start with workflow actions for standard support email processing. For more custom workflows (monitoring alerts, scheduled tasks, multi-step automations), use API call actions chained together.

Full comparison → Workflow Actions vs. Single API Call Actions

The Processing Log​

Every email that arrives at any of your mailboxes is recorded in History. Each entry has a full execution log showing:

  • Which rules matched and in what order
  • Every action step that ran, with its configuration at the time it ran
  • Every API call made to Autotask, including the payload sent and the response received
  • The state of all custom.* variables at each step
  • Any errors or exceptions, including the exact error message from the Autotask API

This log is the primary tool for understanding why something worked or did not work. When troubleshooting, open the history entry, expand the steps, and read what happened.

Replay: The Play button on any history entry re-processes the same email through your current rule configuration. You do not need to send a new test email after adjusting a rule. Just replay the existing entry.

Dedicated Mailboxes per Integration​

A key principle for keeping your workflows maintainable: use a dedicated mailbox for each third-party tool or use case.

Email addresses in Email2AT are free. Instead of routing all email through a single support mailbox with complex expressions to sort it out, create separate mailboxes:

This makes each mailbox's rules simpler, makes History easier to read, and means a problem in one workflow cannot interfere with another.

What's Next​