Handling MailCare Webhooks - MailCare Documentation

Introduction

This documentation explains how to handle webhooks generated by MailCare automations, including the request headers and body structure you will receive in your application. MailCare allows you to create automations via the web interface or API, enabling the generation of webhooks on your application for each received email that matches the defined rules in the automations. For instance, if you want to receive a webhook on your application every time an email with an attachment arrives on MailCare, you need to:

Begin by creating an automation via API or Web with the title catch email with attachment and check the box Trigger on Attachment, then enter the Webhook URL to Call, which is the URL of your application.
Next, in your application, you just need to handle this incoming request, which will be a POST on the URL defined above.

Screenshot of creating an automation via webhook

Request Headers

Here is the list of request headers you could receive:

Accept: application/vnd.mailcare.v1+json
X-MailCare-Title: Save pdf invoices
X-MailCare-Subject: HIT
X-MailCare-Sender: HIT
X-MailCare-Inbox: HIT
X-MailCare-Has-Attachments: HIT
X-MailCare-Secret-Token: SECRET12345$

The X-MailCare-* headers provide information about why you are receiving this request, which automation generated this webhook, and what match was made.

Request Body in JSON Metadata Email

If you select the following format JSON Metadata Email (Content-Type: application/json)

{
  "data": {
    "id": "9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d",
    "sender": {
      "id": "9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d",
      "display_name": "Louis",
      "email": "louis@example.com",
      "created_at": "2018-01-19T12:23:27+00:00",
      "updated_at": "2018-01-19T12:23:27+00:00"
    },
    "inbox": {
      "id": "9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d",
      "display_name": "Claire",
      "email": "claire@example.com",
      "created_at": "2018-01-19T12:23:27+00:00",
      "updated_at": "2018-01-19T12:23:27+00:00"
    },
    "carbon_copies": [
      {
        "display_name": "Thomas",
        "email": "thomas@example.com"

      },
      {
        "display_name": "Angel",
        "email": "angle@example.com"

      }
    ],
    "subject": "Welcome to mailcare.io",
    "created_at": "2018-01-19T12:23:27+00:00",
    "read": "2018-01-19T12:23:27+00:00",
    "favorite": false,
    "has_html": true,
    "has_text": true,
    "size_in_bytes": 40240,
    "attachments": [
      {
        "id": "238515b6-9a2f-4797-aed6-e7d36a7df430",
        "email_id": "7dfc9fea-c496-4623-8784-de53706dad7f",
        "headers_hashed": "b84bcb9dfc8d0a17a089073c0355ad58",
        "file_name": "signature.jpg",
        "content_type": "image/jpg",
        "size_in_bytes": 33996,
        "created_at": "2018-01-19 12:23:27",
        "updated_at": "2018-01-19 12:23:27",
        "size_for_human": "34.00kB"
      }
    ]
  }
}

Request Body in RAW Email

If you select the following format RAW Email (Content-Type: message/rfc2822)

From test@example.com  Sun Jun 16 17:50:14 2013
MIME-Version: 1.0
Date: Sun, 16 Jun 2013 17:50:12 +0200
Subject: =?ISO-8859-1?Q?Mail_avec_fichier_attach=E9_de_1ko?=
From: Name <test@example.com>
To: test@example.com
Content-Type: multipart/mixed; boundary=047d7b1635f77236f404df476f85

--047d7b1635f77236f404df476f85
Content-Type: multipart/alternative; boundary=047d7b1635f77236f004df476f83

--047d7b1635f77236f004df476f83
Content-Type: text/plain; charset=ISO-8859-1

this is text part

--047d7b1635f77236f004df476f83
Content-Type: text/html; charset=ISO-8859-1

<div>this is html part</div>

--047d7b1635f77236f004df476f83--
--047d7b1635f77236f404df476f85
Content-Type: application/octet-stream; name=attach01
Content-Disposition: attachment; filename=attach01
Content-Transfer-Encoding: base64
X-Attachment-Id: f_hi0eudw60

YQo=
--047d7b1635f77236f404df476f85--

Request Body in JSON Metadata Email with HTML/Text Bodies

If you select the following format JSON Metadata Email with HTML/Text Bodies (Content-Type: application/json)

{
  "data": {
    "id": "9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d",
    "sender": {
      "id": "9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d",
      "display_name": "Louis",
      "email": "louis@example.com",
      "created_at": "2018-01-19T12:23:27+00:00",
      "updated_at": "2018-01-19T12:23:27+00:00"
    },
    "inbox": {
      "id": "9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d",
      "display_name": "Claire",
      "email": "claire@example.com",
      "created_at": "2018-01-19T12:23:27+00:00",
      "updated_at": "2018-01-19T12:23:27+00:00"
    },
    "carbon_copies": [
      {
        "display_name": "Thomas",
        "email": "thomas@example.com"

      },
      {
        "display_name": "Angel",
        "email": "angle@example.com"

      }
    ],
    "subject": "Welcome to mailcare.io",
    "created_at": "2018-01-19T12:23:27+00:00",
    "read": "2018-01-19T12:23:27+00:00",
    "favorite": false,
    "has_html": true,
    "has_text": true,
    "size_in_bytes": 40240,
    "attachments": [
      {
        "id": "238515b6-9a2f-4797-aed6-e7d36a7df430",
        "email_id": "7dfc9fea-c496-4623-8784-de53706dad7f",
        "headers_hashed": "b84bcb9dfc8d0a17a089073c0355ad58",
        "file_name": "signature.jpg",
        "content_type": "image/jpg",
        "size_in_bytes": 33996,
        "created_at": "2018-01-19 12:23:27",
        "updated_at": "2018-01-19 12:23:27",
        "size_for_human": "34.00kB"
      }
    ],
    "html": "<div>this is html part</div>",
    "text": "this is text part",
  }
}

How to Integrate MailCare with Your Laravel 11 Application

For a detailed guide on integrating MailCare with your Laravel 11 application, you can read the following blog post: Read the following blog post

​Introduction

​Request Headers

​Request Body in JSON Metadata Email

​Request Body in RAW Email

​Request Body in JSON Metadata Email with HTML/Text Bodies