Smartflow Validation Rules

This endpoint returns the currently active rules used to validate the structure and configuration of Smartflow graphs.

Validation checks whether activities can be connected, whether required activities exist upstream, whether forbidden activities or configurations are present, and whether connection counts or individual parameters are valid.

Rule set format

{
  "version": 1,
  "rules": [
    {
      "id": "unique-rule-id",
      "scope": "ancestorForbidden",
      "severity": "error",
      "subjectTypes": ["target_abtest"],
      "relatedTypes": ["trigger_start"],
      "relatedParams": {"sendTimeOptimization": true},
      "message": "A/B testing cannot be used while send-time optimization is enabled"
    }
  ]
}

Every rule has a unique id and a scope. subjectTypes identifies the activity to which the rule applies. Type lists support the wildcard "*", meaning any activity type.

Validation severity

error — the operation is rejected until the validation problem is fixed.

warning — the operation may continue, but the problem is reported as a validation warning.

Rule scopes

`parent` and `child`

Check which activity types may be directly connected.

{
  "id": "email-must-follow-filter",
  "scope": "parent",
  "effect": "allow",
  "subjectTypes": ["action_email"],
  "relatedTypes": ["target_filter"],
  "passThroughTypes": ["action_delay"]
}

For parent, passThroughTypes allows the validator to look past transparent activities, such as a delay, when determining the relevant upstream activity.

A deny rule rejects a matching connection:

{
  "id": "condition-only-after-email",
  "scope": "parent",
  "effect": "deny",
  "severity": "error",
  "subjectTypes": ["target_condition"],
  "relatedTypes": ["*"],
  "message": "A condition must follow an eligible send activity"
}

Matching allow rules take precedence over matching deny rules. If no rule matches, the connection is allowed by default.

`ancestorRequired`

Requires at least one activity of a listed type anywhere upstream in the same branch.

{
  "id": "send-requires-narrowing",
  "scope": "ancestorRequired",
  "severity": "error",
  "subjectTypes": ["action_email", "action_sms", "action_social"],
  "relatedTypes": ["target_filter", "target_condition"],
  "requiredIfAncestorTypes": ["trigger_start", "trigger_recurring", "trigger_scheduled_start"],
  "message": "A bulk send must have a contact-narrowing activity upstream"
}

requiredIfAncestorTypes makes the rule conditional. In the example, narrowing is required only when the send is reachable from a bulk trigger. If omitted, the requirement always applies.

`ancestorForbidden`

Rejects a subject when a listed activity is present anywhere upstream.

{
  "id": "abtest-forbidden-send-time-optimization",
  "scope": "ancestorForbidden",
  "severity": "error",
  "subjectTypes": ["target_abtest"],
  "relatedTypes": ["trigger_start", "trigger_recurring", "trigger_scheduled_start"],
  "relatedParams": {"sendTimeOptimization": true},
  "message": "A/B testing cannot be used while send-time optimization is enabled"
}

relatedParams is an optional predicate on the matching upstream activity. Every listed parameter must have exactly the specified value. The upstream activity must match both relatedTypes and relatedParams; a matching activity type with a different value does not violate the rule.

For example, the rule above rejects an A/B test only when an upstream bulk trigger has sendTimeOptimization set to true. A value of false or an omitted value does not match this predicate.

subjectParams is the equivalent predicate for the subject activity itself:

{
  "id": "open-filter-after-email",
  "scope": "parent",
  "effect": "allow",
  "subjectTypes": ["target_condition"],
  "subjectParams": {"filter": "open"},
  "relatedTypes": ["action_email", "target_abtest"]
}

Both parameter predicates are optional and use strict equality for each listed key.

`cardinality`

Limits the number of upstream and downstream connections.

{
  "id": "cardinality-merge",
  "scope": "cardinality",
  "subjectTypes": ["target_merge"],
  "minAncestors": 1,
  "maxAncestors": null,
  "maxDescendants": 1,
  "severity": "error"
}

null means unlimited. The first matching cardinality rule is used, so specific rules should precede a wildcard rule.

`param`

Checks one parameter on the subject activity.

{
  "id": "scheduled-start-datetime-future",
  "scope": "param",
  "severity": "warning",
  "subjectTypes": ["trigger_scheduled_start"],
  "field": "startDateTime",
  "check": "futureDateTime",
  "whenSmartflowState": ["running"],
  "message": "The scheduled start must be in the future"
}

Supported checks:

futureDateTime — the specified value must represent a future date and time. Empty values are skipped.

paramPresent — the specified parameter must have a truthy value.

whenSmartflowState optionally limits the rule to selected Smartflow states. Without it, the rule applies in every state.

`flow`

Checks the Smartflow as a whole rather than one activity.

{
  "id": "max-one-start",
  "scope": "flow",
  "effect": "deny",
  "severity": "error",
  "check": "maxCountByType",
  "types": ["trigger_start"],
  "max": 1,
  "message": "A Smartflow may contain only one immediate trigger"
}

Supported checks:

maxCountByType — rejects the flow when the number of matching activities exceeds max.

requiresTypePresent — rejects the flow when none of the listed activity types is present.

Examples of built-in validation behavior

A/B tests may be used only in campaigns started by a bulk or scheduled trigger. They cannot be used when an upstream bulk trigger has sendTimeOptimization: true.

A bulk email, SMS, or social send must have a target_filter or target_condition somewhere upstream.

A target_condition may follow action_email, action_sms, action_social, or target_abtest (through action_delay); for filter="open", the upstream activity must be action_email or target_abtest.

Website popup and teaser activities must be connected to a website-viewed trigger, allowing transparent activities in between.

A Double Opt-In activity must follow a compatible form or externally supplied contact-data source.

Trigger activities may be roots, while ordinary activities require an upstream activity.

Merge, split, condition, and other branching activities have specific connection-count limits.

Custom messages

A rule may define a custom message. The placeholders {subjectType} and {relatedType} are replaced with the actual activity types when applicable. If no message is provided, a generic validation message is generated.

The response from this endpoint is the active rule set used by Smartflow validation. The exact set may change as validation policy evolves.

`target_abtest` condition

The target_abtest activity must define params.condition. The value is normalized by trimming whitespace and converting it to lowercase, so the accepted values are:

open — evaluate the variants by unique email opens.

click — evaluate the variants by unique email clicks.

A missing value or any other value is invalid and must be reported as a validation error before the Smartflow can be saved or executed. The condition applies to the A/B test activity itself; it is independent of the upstream trigger and target connection rules.

{ "version": 0, "rules": [ { "id": "string", "scope": "string", "effect": "string", "severity": "string", "subjectTypes": [ "string" ], "relatedTypes": [ "string" ], "property1": "string", "property2": "string" } ] }

Get Smartflow Validation Rules

Smartflow Validation Rules

Rule set format

Validation severity

Rule scopes

`parent` and `child`

`ancestorRequired`

`ancestorForbidden`

`cardinality`

`param`

`flow`

Examples of built-in validation behavior

Custom messages

`target_abtest` condition

Request

Responses

Get Smartflow Validation Rules

Smartflow Validation Rules#

Rule set format#

Validation severity#

Rule scopes#

parent and child#

ancestorRequired#

ancestorForbidden#

cardinality#

param#

flow#

Examples of built-in validation behavior#

Custom messages#

target_abtest condition#

Request

Responses

Smartflow Validation Rules

Rule set format

Validation severity

Rule scopes

`parent` and `child`

`ancestorRequired`

`ancestorForbidden`

`cardinality`

`param`

`flow`

Examples of built-in validation behavior

Custom messages

`target_abtest` condition