Email Webhooks

ImprovMX can send incoming emails as structured JSON to your server, allowing you to build more complex email forwarding infrastructure.

NOTE: Webhooks are a premium feature.

Configuration

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.

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": "example@yourdomain.com",
        "DKIM-Signature": ["v=1; a=rsa-sha256; c=relaxed/relaxed; d=improvmx.com; i=@improvmx.com; 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": "example@yourdomain.com"
        }
    ],
    "from": {
        "name": "Email Test",
        "email": "test@example.com"
    },
    "subject": "This is a sample email to show the webhooks",
    "message-id": "random-message-id-generated@example.com",
    "date": "Thu, 13 Feb 2020 13:44:12 -0800",
    "return-path": {
        "name": null,
        "email": "test@example.com"
    },
    "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