Webhooks

Configuration

Using Aliases

To enable a webhook, input a URL (starting with http:// or https://) as one of your alias' forward destinations in the app console.

TIP: We recommend using webhook.site or webhook.cool to generate a free, no-account-needed webhook to test this feature. Just paste in their generated webhook URL, and click our TEST button.

You can specify multiple destination email addresses or webhooks for a single alias by separating each with a comma.

Using Rules Routing

Rules Routing also supports sending emails to a webhook URL.

Rules work with matching logic (e.g., regex, CEL) and allow webhook destinations just like aliases.

Example:

Webhook payloads sent through Rules are identical to those sent through Aliases.

Payload

For each incoming email, we send a POST request to your URL with the following JSON in the body:

{
    "headers": {
        "X-Forwarding-Service": "ImprovMX v3.0.0",
        "Received-SPF": [
          "pass (improvmx.com: domain of example.com designates xxx.xxx.xxx.xxx as permitted sender) receiver=mx1.improvmx.com; client-ip=xxx.xxx.xxx.xxx; helo=example.com;"
        ],
        "Delivered-To": "[email protected]",
        "DKIM-Signature": [
          "v=1; a=rsa-sha256; c=relaxed/relaxed; d=improvmx.com; [email protected]; q=dns/txt; s=20191126; t=1581630208; h=date : from : to : subject : content-type : message-id; bh=XXX=; b=XXX=="
        ],
        "Authentication-Results": [
          "mx1.improvmx.com; spf=pass (improvmx.com: domain of example.com designates xxx.xxx.xxx.xxx as permitted sender) smtp.mailfrom=example.com; dkim=none"
        ]
    },
    "to": [
        {
            "name": "Example user",
            "email": "[email protected]"
        }
    ],
    "from": {
        "name": "Email Test",
        "email": "[email protected]"
    },
    "subject": "This is a sample email to show the webhooks",
    "message-id": "[email protected]",
    "date": "Thu, 13 Feb 2020 13:44:12 -0800",
    "return-path": {
        "name": null,
        "email": "[email protected]"
    },
    "timestamp": 1581601452,
    "text": "Sample text in the email's body as the text/plain value.[image: screenshot.png]",
    "html": "Sample text in the email's body as the text/html value.",
    "inlines": [
        {
            "type": "image/png",
            "name": "screenshot.png",
            "content": "{base64_encoded_data}",
            "cid": "some_random_id"
        }
    ],
    "attachments": [
        {
            "type": "application/pdf",
            "name": "all-life-secrets.pdf",
            "content": "{base64_encoded_data}",
            "encoding": "binary"
        },
        {
            "type": "application/pdf",
            "name": "getting-out-of-the-simulation.pdf",
            "content": "{base64_encoded_data}",
            "encoding": "binary"
        }
    ]
}

Status Codes & Retries

If we receive a status code of 2xx, we consider the delivery successful. Otherwise, for status codes of 4xx or 5xx, we make two additional retry attempts. If after all the retries, we are unable to deliver the request to your web server, we stop trying.

IP Whitelisting

To ensure that requests come from a trusted source, we recommend whitelisting the ImprovMX webhook server IP. This allows incoming traffic from that IP address to bypass security measures, while blocking all other incoming traffic.

It is important to only whitelist trusted IP addresses to ensure the security and integrity of your system. ImprovMX webhooks will always come from the following static IP address:

15.237.103.194