The Webhook plugin can be configured against your Customer Space to send raw recipient email activity to a URL endpoint in your system in near-real-time. It is typically used to add logs of recipient activity into a third-party CRM system.

Maxemail will send the raw event data to the URL provided by the client. Although it's possible to configure which events are sent, the data that is included cannot be adjusted.

To enable webhooks, please contact the Support Team with the target URL and the list of events & customer space(s) which should be configured.

URL

You must provide Xtremepush with a URL to which Maxemail will send the data. Only one URL can be configured per Customer Space. The URL must be secure (ie. HTTPS) as the events contain protected recipient data.

🚧
Success response
Your platform must respond with a 200 OK HTTP header. When Maxemail doesn't receive a 200 OK header, the event will be attempted again with an increasing delay of up to 3 hours, for a maximum of 3 days. At this point, the Webhook job will be discarded.

Agency spaces

For clients with agency spaces, it's possible for the Webhook URL to be configured at the parent agency-level, so that all of the customer spaces send events to the same URL. This may provide simpler configuration, and save having to ask for Webhooks to be enabled when new customer spaces are added.

Events

The following events are available, across Email Campaigns, Triggered Emails and Transactional SMTP:

send
bounce
open
click
unsubscribe
track (ROI, not available for Transactional SMTP)
complete (ROI, not available for Transactional SMTP)
delete (Fired immediately before the Recipient is permanently deleted)

By default all event types are sent, but it's possible to configure the plugin to send a subset of these events.

Requests are made to the Webhook URL using the POST method, with the request body containing JSON-encoded array of multiple events. Each nested event object has an event key containing the event name as a string, and a data key containing an object for all the event properties.

The properties available within the event data vary by event type, however recipient_id, email_address and timestamp would be expected as a minimum. See the examples for more details about what properties are included.

📘
Legacy format
Clients using the legacy Webhook format will receive events as GET requests with a single event with event and data parameters. To upgrade to the current version, please speak to the Support Team.

Identifiers

The IDs provided in events are scoped to a single customer space. If you are receiving events for multiple spaces, it's important to recognise that, for example, recipient 123 in one customer is not the same as recipient 123 in another customer.

Customer IDs (and corresponding names) are provided to help differentiate the source of the events, and should be used in combination with relevant IDs to identify unique recipients, emails, etc.

Examples

Email Campaigns & Triggered Emails

{
    "event": "send",
    "data": {
        "email_id": 123,
        "subject_line": "Email Subject 123",
        "description": "Preview text",
        "from_address": "from@example.com",
        "from_address_alias": "From Name",
        "reply_to": "reply@example.com",
        "reply_to_alias": "Reply Name",
        "use_opens": 1,
        "use_click_thrus": 1,
        "use_roi": 0,
        "list_total": 4598,
        "total_sent": 4598,
        "scheduled_ts": "2016-12-07 11:30",
        "start_ts": "2016-12-07 11:31",
        "finish_ts": "2016-12-07 11:32",
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680
    }
}

{
    "event": "send",
    "data": {
        "email_id": 123,
        "subject_line": "Email Subject 123",
        "description": "Preview text",
        "from_address": "from@example.com",
        "from_address_alias": "From Name",
        "reply_to": "reply@example.com",
        "reply_to_alias": "Reply Name",
        "use_opens": 1,
        "use_click_thrus": 1,
        "use_roi": 0,
        "list_total": null,
        "total_sent": 4598,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680
    }
}

{
    "event": "bounce",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "hard_bounce": true,
        "bounce_code": 500,
        "bounce_reason": "0176 other \"Delivery to the following recipients failed.\r\n\r\n recipient@example.com\"",
        "bounce_category": "other"
    }
}

{
    "event": "open",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "client_name": "AppleMail",
        "device_name": "Mac 10.13"
    }
}

{
    "event": "click",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "device_name": "Mac 10.13",
        "link_id": 15063,
        "link_url": "https:\/\/www.example.com\/?key1=value1&key2=value2"
    }
}

{
    "event": "unsubscribe",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "unsubscribe_method": "feedback"
    }
}

{
    "event": "unsubscribe",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "device_name": "Mac 10.13",
        "unsubscribe_method": "form",
        "link_id": 15067,
        "link_type": "local"
    }
}

{
    "event": "track",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "revenue": 20054
    }
}

{
    "event": "complete",
    "data": {
        "email_id": 123,
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "revenue": 20054,
        "reference": "ORD12345"
    }
}

Transactional Emails

{
    "event": "send",
    "data": {
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
        "message_id": "recipient+575a7d0c56fae@example.com",
        "from_address": "from@example.com",
        "subject_line": "Email Subject 123",
        "sent_ts": "2016-12-05 11:24:56",
        "bcc_address": "bcc@example.com",
        "hasHtml": true,
        "hasText": true,
        "attachments": 0,
        "checkUnsubs": false,
        "ignoreBounces": false,
        "trackOpens": true,
        "trackClicks": true,
        "tags": [
            "taga",
            "tagb"
        ]
    }
}

{
    "event": "bounce",
    "data": {
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
        "message_id": "recipient+575a7d0c56fae@example.com",
        "hard_bounce": true,
        "bounce_reason": "0176 other \"Delivery to the following recipients failed.\r\n\r\n recipient@example.com\""
    }
}

{
    "event": "open",
    "data": {
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
        "message_id": "recipient+575a7d0c56fae@example.com",
        "client_name": "AppleMail",
        "device_name": "Mac 10.13"
    }
}

{
    "event": "click",
    "data": {
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
        "message_id": "recipient+575a7d0c56fae@example.com",
        "device_name": "Mac 10.13",
        "link_id": 15063,
        "link_url": "https:\/\/www.example.com\/?key1=value1&key2=value2"
    }
}

{
    "event": "unsubscribe",
    "data": {
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680,
        "trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
        "message_id": "recipient+575a7d0c56fae@example.com",
        "unsubscribe_method": "feedback"
    }
}

Recipient

{
    "event": "delete",
    "data": {
        "customer_id": 111,
        "customer_name": "Customer Name",
        "recipient_id": 12358,
        "email_address": "recipient@example.com",
        "timestamp": 1480688680
    }
}