← Back to docs

MailCare API Documentation

• Introduction
  • Versions
  • Authentication
  • Base URL
• Endpoints Reference
  • Retrieve emails
  • Retrieve email by ID
  • Retrieve attachment by ID
  • Delete an email
  • Favorite an email
  • Unfavorite an email
  • Retrieve statistics
  • Retrieve automations
  • Create automation
  • Update automation
  • Delete automation
• Contact

Introduction

Versions

By default, all requests receive the last version of the REST API. We encourage you to explicitly request this version via the Accept header if you're building an application and care about the stability of the API.

Accept: application/vnd.mailcare.v1+json

Authentication

Authentication is required to access MailCare API endpoints. To authenticate, you need to generate an API token via the "Api Tokens" menu with the appropriate permissions. Once generated, include the token in the Authorization header with the Bearer scheme.

Authorization: Bearer YOUR_TOKEN_HERE

Base URL

All API calls should be made to the following base URL:

https://mailcare.io/api/teams/{teamId}

This serves as the base URL for all API requests. Replace {teamId} with the appropriate team identifier.

The {teamId} can be found in the URL of the team settings page within the web interface.

← Back

Endpoints Reference

Retrieve Emails

GET /emails

Parameter	Description	Example	Type	Required
page	Page requested	2 (Default: 1)	Number	Optional
limit	Maximum number of emails to retrieve	100 (Default: 25)	Number	Optional
inbox	Filter by inbox	test@example.com	String	Optional
sender	Filter by sender	test@example.com	String	Optional
subject	Search by subject (joker * accepted)	Welcome	String	Optional
since	Include only emails after date	2018-01-19T12:23:27+00:00	String	Optional
until	Include only emails before date	2018-01-19T12:23:27+00:00	String	Optional
search	Search by inbox/sender/subject	matching	String	Optional
unread	Filter only by unread	true	Boolean	Optional
favorite	Filter only by favorite	true	Boolean	Optional

Success Response (200)

{
  "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"
        }
      ]
    }
  ],
  "links": {
    "first": "https://mc3.email/api/emails?page=1",
    "last": "https://mc3.email/api/emails?page=12",
    "prev": "https://mc3.email/api/emails?page=6",
    "next": "https://mc3.email/api/emails?page=8"
  },
  "meta": {
    "current_page": 7,
    "from": 1,
    "last_page": 12,
    "path": "https://mc3.email/api/emails",
    "per_page": 25,
    "to": 12,
    "total": 300
  }
}

← Back

Retrieve email by ID

GET /emails/{id}

Parameter	Description	Example	Type	Required
id	ID of the email	9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d	Number	Required

Success Response (200)

{
  "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"
      }
    ]
  }
}

Success Response (200) with the header Accept:text/plain

Welcome to mailcare.io
Follow this link to continue: https://mailcare.io

Success Response (200) with the header Accept:text/html

<div>
    <h1>Welcome to mailcare.io</h1>
    <p>
        Follow this link to continue <a href="https://mailcare.io">mailcare.io</a>
    </p>
</div>

Success Response (200) with the header Accept: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--

← Back

Retrieve attachment by ID

GET /emails/{id}/attachments/{attachmentId}

Parameter	Description	Example	Type	Required
id	ID of the email	9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d	Number	Required
attachmentId	ID of the attachment	238515b6-9a2f-4797-aed6-e7d36a7df430	Number	Required

Success Response (200) The API response will be of mixed content type depending on the type of attachment. If it's a PDF, it will be application/pdf, and if it's a JPEG image, it will be image/jpeg...

← Back

Delete an email

DELETE /emails/{id}

Parameter	Description	Example	Type	Required
id	ID of the email	9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d	Number	Required

Success Response (200)

← Back

Favorite an email

POST /emails/{id}/favorites

Parameter	Description	Example	Type	Required
id	ID of the email	9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d	Number	Required

Success Response (200)

← Back

Unfavorite an email

DELETE /emails/{id}/favorites

Parameter	Description	Example	Type	Required
id	ID of the email	9bf63f3b-4e4e-46a0-8c7d-2d6d32576a1d	Number	Required

Success Response (200)

← Back

Retrieve statistics

GET /statistics

Success Response (200)

{
  "data": [
    {
      "created_at": "2018-01-19",
      "emails_received": 10,
      "inboxes_created": 3,
      "storage_used": 33996,
      "cumulative_storage_used": 33996,
      "emails_deleted": 1
    }
  ],
  "meta": {
    "emails_received": 786,
    "inboxes_created": 68,
    "storage_used_for_human": "48.08MB",
    "storage_used": 48083603,
    "total_space": 148083603,
    "emails_deleted": 9
  }
}

← Back

Retrieve automations

GET /automations

Success Response (200)

{
  "data": [
    {
      "id": "238515b6-9a2f-4797-aed6-e7d36a7df430",
      "title": "Save pdf invoices",
      "sender": "shop@example.com",
      "inbox": "claire@example.com",
      "subject": "New invoice",
      "has_attachments": true,
      "action_url": "https://example.com/webhooks/save-pdf-invoices",
      "action_secret_token": "SECRET12345$",
      "payload_format": "json",
      "action_delete_email": false,
      "emails_received": 10,
      "created_at": "2018-01-19T12:23:27+00:00",
      "updated_at": "2018-01-19T12:23:27+00:00"
    }
  ]
}

← Back

Create automation

POST /automations

Parameter	Description	Example	Type	Required
title	Title of the automation	Save pdf invoices	String	Required
sender	Sender that should match	shop@example.com	String	Optional
inbox	Inbox that should match	claire@example.com	String	Optional
subject	Subject that should match	New invoice	String	Optional
has_attachments	Email should have at least one attachment	true	Boolean	Optional
action_url	URL that will be called	https://example.com/webhooks/save-pdf-invoices	String	Optional
action_secret_token	Use this token to validate received payloads	SECRET12345$	String	Optional
action_delete_email	Email shoud be deleted	true	Boolean	Optional
payload_format	Paylod format to use	json or raw or json_with_bodies	String	Optional

Success Response (201)

← Back

Update automation

PUT /automations/{id}

Parameter	Description	Example	Type	Required
id	ID of the automation	238515b6-9a2f-4797-aed6-e7d36a7df430	String	Required
title	Title of the automation	Save pdf invoices	String	Required
sender	Sender that should match	shop@example.com	String	Optional
inbox	Inbox that should match	claire@example.com	String	Optional
subject	Subject that should match	New invoice	String	Optional
has_attachments	Email should have at least one attachment	true	Boolean	Optional
action_url	URL that will be called	https://example.com/webhooks/save-pdf-invoices	String	Optional
action_secret_token	Use this token to validate received payloads	SECRET12345$	String	Optional
action_delete_email	Email shoud be deleted	true	Boolean	Optional
payload_format	Paylod format to use	json or raw or json_with_bodies	String	Optional

Success Response (200)

← Back

Delete automation

DELETE /automations/{id}

Parameter	Description	Example	Type	Required
id	ID of the automation	238515b6-9a2f-4797-aed6-e7d36a7df430	String	Required

Success Response (200)

Contact

For any questions or support, please contact vincent@mailcare.io.

← Back