Enrich a conversation from a webhook

Receive a webhook, look up a customer in your CRM, and attach the result to the conversation as custom fields.

A common integration is: when a message arrives, look up the sender in your CRM, find the relevant customer record (claim number, account ID, region, etc.), and attach that information to the Emailgistics conversation so agents see it without leaving Outlook.

Prerequisites

An Emailgistics mailbox with the Webhooks feature enabled (contact support if it isn’t).
Custom fields configured on the mailbox — for example, claimNumber and policyNumber. Custom fields are named slots a mailbox administrator defines in Admin; once defined, agents see them in the add-in conversation panel and integrations like this one can write to them. Configure them under the mailbox’s Custom Fields tab in Emailgistics Admin.
An HTTPS endpoint of your own that can receive a JSON POST and return JSON.

The flow

A message arrives, your endpoint is called

Configure a webhook in Admin (see Setting up a webhook) pointed at your endpoint, with Include Custom Fields enabled if you want to see the conversation’s existing values.

Emailgistics POSTs the message details to you. The relevant fields here are from.emailAddress.address (who sent the message) and conversationId (the conversation your data will be attached to).

Your endpoint looks up the sender

Use whatever logic makes sense — query your CRM by sender domain, look up by email, run a fraud check, etc.

sender_email = payload["from"]["emailAddress"]["address"]
customer = crm.find_by_email(sender_email)
if customer is None:
    return {"status": "success", "message": "No CRM record; nothing to enrich."}

Return a `setCustomFields` action

Build the response with the values you want to write. Unknown keys (not configured for the mailbox) are silently dropped, so it’s safe to include extra fields.

{
  "status":  "success",
  "message": "Enriched from CRM lookup",
  "actions": [
    {
      "type": "setCustomFields",
      "name": "Apply CRM context",
      "value": {
        "claimNumber":  "CLM-556677",
        "policyNumber": "POL-889900",
        "region":       "EMEA"
      }
    }
  ]
}

Emailgistics writes those values onto the conversation — see setCustomFields action.

(Optional) Add other actions

actions[] can carry multiple actions. A typical enrichment also tags the message and assigns to the right team:

{
  "status":  "success",
  "message": "Enriched from CRM lookup",
  "actions": [
    {
      "type": "setCustomFields",
      "name": "Apply CRM context",
      "value": {
        "claimNumber":  "CLM-556677",
        "policyNumber": "POL-889900"
      }
    },
    {
      "type": "tag",
      "name": "Tag VIP",
      "value": { "tags": ["VIP"] }
    },
    {
      "type": "assign",
      "name": "Assign to claims",
      "value": {
        "mainAssignment": {
          "users":             ["Joe Cool"],
          "ignoreMaxMessages": true
        }
      }
    }
  ]
}

Actions execute in order. See Response envelope for behavior on partial failures.

End-to-end Python sketch

import hmac
import os

from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["EMAILGISTICS_WEBHOOK_SECRET"]

@app.post("/emailgistics-webhook")
def webhook():
    auth = request.headers.get("Authorization", "")
    if not auth.startswith("Bearer ") or not hmac.compare_digest(auth[7:], WEBHOOK_SECRET):
        return ("", 401)

    payload = request.get_json()
    if payload.get("event") != "received":
        return jsonify({"status": "success", "message": "Event ignored."})

    sender = payload["from"]["emailAddress"]["address"]
    customer = crm.find_by_email(sender)
    if customer is None:
        return jsonify({"status": "success", "message": "No CRM record."})

    return jsonify({
        "status":  "success",
        "message": f"Enriched from CRM record {customer.id}.",
        "actions": [
            {
                "type": "setCustomFields",
                "name": "Apply CRM context",
                "value": {
                    "claimNumber":  customer.claim_number,
                    "policyNumber": customer.policy_number,
                    "region":       customer.region,
                },
            }
        ],
    })

What to watch for

Idempotency. Emailgistics retries on connection errors and 5xx, so your handler may run twice for the same message. setCustomFields is naturally idempotent (writing the same values again is a no-op), but if you do other side effects (writing to your own DB, sending external notifications), guard them by payload["id"] or payload["internetMessageId"].
Slow CRM calls. Emailgistics waits up to 100 seconds for your response. If your lookup exceeds that, the webhook times out and the message isn’t enriched — there’s currently no way to apply actions after the response is sent. Keep the request path fast: cache common lookups, pre-fetch on a schedule, or fall back to a cheaper signal (domain-only match, last-known values) when the slow path can’t make the deadline.
Validation rules. Custom field values longer than 100 characters are truncated; values that fail the field’s regex are dropped. Check your field configurations in Admin.

Enrich a conversation from a webhook

On this page