Assign action

Assigns the message to a user. You can specify a primary set of candidates and one or more backup sets that are tried in order if the primary fails (for example, when no primary candidate is available).

{
  "name":  "Assign to insurance team",
  "type":  "assign",
  "value": {
    "mainAssignment": {
      "users":              ["Joe Cool", "jerri.fallon@pinnilly.com"],
      "ignoreAvailability": false,
      "ignoreMaxMessages":  true,
      "aaMethod":           1
    },
    "backupAssignments": [
      {
        "assignToAnyUser":                    true,
        "ignoreAvailability":                 false,
        "ignoreMaxMessages":                  false,
        "assignIfUserAvailableWithinMinutes": 120,
        "aaMethod":                           2
      }
    ]
  }
}

Action object

type"assign"

Always "assign".

name?string

Optional label for diagnostics — appears in Admin logs and error messages.

valueobject

The assignment specification — see below.

`value`

mainAssignmentAssignmentSpec

The primary assignment attempt — see Assignment specification.

backupAssignments?AssignmentSpec[]

Tried in order if mainAssignment cannot complete (no eligible users). Stops at the first one that succeeds. Each entry is a full Assignment specification with either a users list or assignToAnyUser set to true.

Assignment specification

Each assignment specification narrows down a candidate pool, then load-balances the assignment among the eligible users. Either users or assignToAnyUser must be set — not both.

The same specification is used for both mainAssignment and every entry in backupAssignments. A backup can therefore target a specific named users list — use this to express strict priority between named users (try user A, then a specific user B), rather than falling back to the whole mailbox via assignToAnyUser.

users?string[]

Candidate pool by display name (as shown in the Admin Users list) or email address. Matching is case-insensitive. Unknown names and emails are silently dropped.

assignToAnyUser?booleandefault false

When true, the candidate pool is every user in the mailbox. Mutually exclusive with users.

ignoreAvailability?booleandefault false

When true, ignore user availability schedules.

ignoreMaxMessages?booleandefault true

When true, ignore each user’s “max messages” setting. Defaults to true so a webhook-triggered assignment isn’t blocked by a per-user cap; this matches the default for the equivalent Admin rule action.

assignIfUserAvailableWithinMinutes?integer

When checking availability, also count users who will become available within this many minutes (in the mailbox’s configured time zone). Ignored if ignoreAvailability is true.

aaMethod?0 | 1 | 2default 0

Auto-assignment method used to pick a user from the eligible candidate pool. 1 = round-robin (rotate through users in order), 2 = load-balanced (assign to the user with the most available slots). 0 (or omitted) defaults to load-balanced.

Behavior

If the primary mainAssignment finds no eligible user, Emailgistics tries each entry in backupAssignments in order until one succeeds.
Unknown entries in users[] (names or emails that don’t match any user, case-insensitive) are silently dropped before the eligibility check.
If no specification produces an eligible user, the message is left unassigned and processing moves on.

Example: priority routing to specific users

Strict priority between two named users: assign to the case manager whenever they’re available, and only if they’re not, assign to a specific co-manager — never load-balanced across the whole mailbox. Each spec names a single user, so the message goes to that exact person.

{
  "type": "assign",
  "name": "Case manager, then co-manager",
  "value": {
    "mainAssignment": {
      "users":              ["Ina Williams"],
      "ignoreAvailability": false,
      "ignoreMaxMessages":  true
    },
    "backupAssignments": [
      {
        "users":              ["Judith Peron"],
        "ignoreAvailability": false,
        "ignoreMaxMessages":  true
      }
    ]
  }
}

When Ina is available the message goes to her. When she is unavailable it falls through to Judith. When neither is available the message is left unassigned.

Example: named primary with whole-mailbox backup

Try the named insurance team first; if none of them are available, fall back to anyone in the mailbox who’ll be available within two hours.

{
  "type": "assign",
  "name": "Insurance with fallback",
  "value": {
    "mainAssignment": {
      "users":              ["Joe Cool", "jerri.fallon@pinnilly.com"],
      "ignoreAvailability": false,
      "ignoreMaxMessages":  true,
      "aaMethod":           1
    },
    "backupAssignments": [
      {
        "assignToAnyUser":                    true,
        "ignoreAvailability":                 false,
        "ignoreMaxMessages":                  false,
        "assignIfUserAvailableWithinMinutes": 120,
        "aaMethod":                           2
      }
    ]
  }
}