Request payload

Everything Emailgistics sends to your endpoint when a message triggers a webhook.

Each webhook delivery is an HTTPS POST request with a JSON body.

Headers

User-Agentstring

Identifies the Emailgistics service version. Format: Emailgistics/<version>.

Content-Typestring

Always application/json.

Authorization?string

Bearer token containing the secret you set in the webhook definition. Validate this on every request. Omitted when no secret is configured.

Body

Always-present fields:

idstring

Unique identifier for this message.

eventstring

The event type that triggered the webhook. Currently always received. Tolerate unknown values — additional events will be added in future.

internetMessageIdstring

Internet message ID of the email — the value of the Message-ID header, as supplied by Microsoft Graph.

receivedstring (RFC 3339 / ISO 8601 datetime)

When the message was received, as supplied by Microsoft Graph.

mailboxstring

Email address of the shared mailbox the event occurred in.

senderAddress

Envelope sender — { "emailAddress": { "name", "address" } }.

fromAddress

Header From value. Same shape as sender. Differs from sender when the message was sent on behalf of someone else.

toAddress[]

Header To recipients. Array of Address.

ccAddress[]

Header Cc recipients. Array of Address.

subjectstring

Message subject line.

hasAttachmentsboolean

Whether the message has any attachments.

timestampstring (ISO 8601 datetime)

When the webhook event occurred — typically very close to received.

conversationIdstring

Emailgistics conversation identifier — for example, "2L8WYB89Z". This is the same ID that appears in the conversation URL in Emailgistics Admin. Use it with Received Message Detail.

Conditional fields — only present when the corresponding option is enabled in the webhook definition:

bodyText?string

Plain-text version of the message body. Present only when Include message text is checked. HTML messages are converted to plain text before delivery; if the resulting text is empty, the field is omitted entirely.

customFields?Record<string, string>

Key-value map of custom field values for the conversation. Present only when Include Custom Fields is checked AND the conversation has values set for at least one currently-defined mailbox custom-field key. Values left over from keys since deleted from the mailbox are filtered out.

Address shape

{ "emailAddress": { "name": "Adele Vance", "address": "adelev@contoso.OnMicrosoft.com" } }

Example

POST /your-endpoint HTTP/1.1
User-Agent: Emailgistics/2.29.299
Content-Type: application/json
Authorization: Bearer f72jip905bn85.23po0xY1aQ7bL

{
  "id":                "65e0aaef382d2e93ed1ef9bc",
  "event":             "received",
  "internetMessageId": "<YT2189.CANRD01.PROD.OLOOK.COM>",
  "received":          "2026-02-28T16:03:58Z",
  "mailbox":           "info@pinnilly.com",
  "sender":            { "emailAddress": { "name": "Ren Storrie", "address": "rstorrie@pinnilly.com" } },
  "from":              { "emailAddress": { "name": "Ren Storrie", "address": "rstorrie@pinnilly.com" } },
  "to":                [{ "emailAddress": { "name": "Pinnilly Insurance", "address": "info@pinnilly.com" } }],
  "cc":                [],
  "subject":           "Coverage",
  "bodyText":          "I'm reaching out to confirm the details of my current coverage...",
  "hasAttachments":    false,
  "timestamp":         "2026-02-28T16:03:59Z",
  "conversationId":    "2L8WYB89Z",
  "customFields": {
    "claimNumber":  "CLM-556677",
    "policyNumber": "POL-889900"
  }
}

Source IP

Requests originate from a stable IP per region — see Regions and base URLs. Whitelist this IP on your endpoint and reject everything else.

Forward compatibility

New optional fields may be added to this payload at any time. Don’t fail if you see fields you don’t recognize.
New event values may be added. Default-handle unknown events (typically by ignoring the request and returning { "status": "success", "message": "ignored" }).