Find Halo User and Client by Email
The Find Halo User and Client by Email action determines the correct Halo user and client for a given email address. It chains multiple Halo API calls together to match the user by email, then the client by domain, and finally falls back to a configurable catch-all client.
This is a building block workflow action. It performs several Halo API calls in a single step to determine the user and client. Use this as a step in a larger workflow, or use it standalone when you need to determine the correct Halo user and client before calling other actions. If you already know the user or client ID, use Create Halo Ticket directly instead. Learn more about the difference between workflow actions and single API call actions.
When to Use This Action
Use this action when:
- You need to determine a Halo user and client from an email address before creating or updating a ticket
- You want a guaranteed client result even when the sender is unknown, using a catch-all default client
- You are building a custom workflow that branches on the determined user and client
Don't use this action for:
- Creating a ticket directly from an email: Use Create Halo Ticket from Email instead. That action wraps this one together with ticket creation, user creation, and attachment upload.
- Raw user searches by arbitrary criteria: Use Query Halo Users for custom search conditions.
- Raw client searches by arbitrary criteria: Use Query Halo Clients for custom search conditions.
How It Works
The action runs a three-step fallback chain and stops as soon as it determines a client.
Step 1: Match the User by Email
The action searches Halo for a user whose email address exactly matches the provided value. If it finds a user, it fetches that user's client and returns both.
Step 2: Match the Client by Email Domain
If no user matches, the action extracts the domain from the email address (for example, acme.com from [email protected]) and searches Halo clients whose domain matches.
Step 3: Use the Default Client
If neither a user nor a domain match exists, the action returns the configured catch-all default client. This guarantees .client is always populated so downstream actions that require a client always have one.
Configuration
Connection
| Field | Description |
|---|---|
| Halo Connection | Select the Halo connection to use for this action. |
Email Address Resolution
| Field | Description | Default |
|---|---|---|
| Email Address | The email address MSPintegrations will use to query Halo to determine a matching user and client. Supports text expressions. | {{email.from.address}} |
| Default Client | The catch-all client used when no existing user or client can be located in Halo. Lock to choose from a dropdown, or unlock to enter a dynamic value. | Unknown (ID 1) |
Custom Fields
| Field | Description | Default |
|---|---|---|
| Include User Custom Fields | Select user custom fields to include when the action searches for a matching user. | Empty |
| User Custom Field Query | Optionally filter the user search by user custom fields. Unlocked text values support text expressions. | No conditions |
| Include Client Custom Fields | Select client custom fields to include when the action searches for a client by email domain. | Empty |
| Client Custom Field Query | Optionally filter the domain search by client custom fields. Unlocked text values support text expressions. | No conditions |
User and client controls remain separate: the action never applies a user filter to a client query or a client filter to a user query. Client custom field projection and filtering apply only to the domain-search stage. Halo does not support these query parameters when this action fetches a known client by ID for a matched user or for the fallback client.
Error Handling
| Field | Description |
|---|---|
| Error Handling | Action to take if the Halo API returns an error. |
| Option | Behavior |
|---|---|
| Exception | Halt processing and report the error |
| Bounce | Return the email/item to the sender |
| Continue | Continue to the next action |
| Stop | Stop this rule but allow other rules to process |
| Stop All | Stop all processing for this message |
Returned Variables
When you configure Store the results in Variable, the result is an object containing the determined user and client. Access properties using dot syntax.
Example usage: {{custom.myVariable.client.id}}
User Properties
The user record is populated only when the action matches a user by email. If no match is found, .user is null.
| Variable | Type | Description |
|---|---|---|
.user.id | number | The determined user ID |
.user.name | string | The determined user name |
.user.emailaddress | string | The determined user's email address |
.user.client_id | number | The client ID associated with the determined user |
.user.customfields | array | The selected user custom fields returned by Halo |
.user.customfields[].id | number | The Halo user custom field ID |
.user.customfields[].value | mixed | The user custom field value |
Client Properties
The client record is always populated.
| Variable | Type | Description |
|---|---|---|
.client.id | number | The determined client ID |
.client.name | string | The determined client name |
.client.website | string | The determined client website/domain |
.client.customfields | array | The selected client custom fields when Halo returns them from the domain-search stage |
.client.customfields[].id | number | The Halo client custom field ID |
.client.customfields[].value | mixed | The client custom field value |
FAQs
What fields are required?
You must provide a Halo Connection and an Email Address. The Default Client defaults to the "Unknown" client (ID 1) and can be changed to any client in your Halo instance.
How do I use dynamic values for the email address?
The Email Address field defaults to {{email.from.address}}, which resolves to the sender of the current email. You can also reference a value from a previous action, such as {{custom.parsed.senderEmail}}.
What happens if the default client does not exist?
If the default client ID is invalid, the action returns an error and respects the Error Handling setting.
What happens if no user is found but a client is?
.user is null and .client is populated with the client that was determined by domain match or the catch-all default. You can follow up with Create Halo User if you want to create a new user under that client.
Related Actions
- Create Halo Ticket from Email: Create a ticket from an email using this determination logic automatically
- Create Halo User: Create a new Halo user when no match is found
- Create Halo Client: Create a new Halo client when no match is found
- Create Halo Ticket: Create a ticket once the user and client are known
- Query Halo Users: Search Halo users with custom criteria
- Query Halo Clients: Search Halo clients with custom criteria