Response envelope

Your endpoint must respond with HTTP 200 and a JSON body in the format below. 5xx responses (and connection errors) trigger retries; 4xx responses are terminal — see Delivery, retries and security.

Envelope

status"success" | "error"

Whether the webhook handler ran to completion. Must be exactly "success" or "error" — any other value is treated as a logical failure. "success" causes Emailgistics to apply actions. "error" causes Emailgistics to ignore actions (no retry — it’s a logical failure, not a transport failure).

messagestring

Human-readable status message. Logged by Emailgistics and shown in Admin for monitoring and debugging.

actions?Action[]

Actions Emailgistics should apply to the message, in order. See the action references for shape.

Examples

Success with actions

{
  "status":  "success",
  "message": "Enriched from CRM lookup.",
  "actions": [
    {
      "name": "Tag VIP customers",
      "type": "tag",
      "value": { "tags": ["VIP"] }
    },
    {
      "name": "Assign to escalation team",
      "type": "assign",
      "value": {
        "mainAssignment": {
          "users": ["Joe Cool", "Jerri Fallon"],
          "ignoreAvailability": false,
          "ignoreMaxMessages": true
        }
      }
    }
  ]
}

Logical failure

When your endpoint can’t process the message but it isn’t a transport failure (CRM lookup failed, business rule says skip, etc.), return status: "error":

{
  "status":  "error",
  "message": "CRM service unavailable."
}

Actions in the response (if any) are ignored. Emailgistics does not retry — your endpoint is reporting it succeeded in running but had nothing to apply.

How actions are processed

Actions execute in order. Emailgistics is lenient about partial failures within an action:

Unknown user names in assign are silently dropped.
Unknown tag names in tag are silently dropped.
Unknown keys in setCustomFields are silently dropped, as are values that exceed the length cap or fail the field’s validation pattern (see Set custom fields action).

If after dropping unknowns there’s still something to do, the action runs. Processing then continues to the next action. There is currently no customer-visible record of which fields were dropped or why; a future Admin view will surface this.

Action types

Type	Purpose
`assign`	Assign the message to one or more users.
`tag`	Apply tags to the message.
`setCustomFields`	Set custom field values on the conversation.
`sendMessage`	Send a templated or inline reply.
`forwardMessage`	Forward the message to other recipients.

Legacy fields

For backward compatibility with older integrations, the response can also use top-level assignTo and applyTags fields instead of actions. New integrations should use actions. The legacy form is undocumented; contact support if you’re maintaining a legacy integration that needs them.

HTTP status

Return HTTP 200 for both success and error envelopes. error is a logical signal in the body, not a transport-level failure.
Return HTTP 5xx if your endpoint genuinely failed and you want Emailgistics to retry. See Delivery, retries and security.
Return HTTP 401 if the Authorization header doesn’t match your expected secret. Emailgistics treats any 4xx response as terminal and won’t retry.

Response envelope

On this page