How to use webhooks to receive emails in your apps

A quick note: Webhooks are only available on Paid plans.

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

Configuration

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

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 4xxor 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

Still have questions?

If you have any other queries please get in touch with our support team.

Was this helpful?