openapi: 3.0.0
info:
title: MailCare API
version: '1.0'
description: API documentation for MailCare
servers:
- url: 'https://mailcare.io/api/teams/{teamId}'
variables:
teamId:
default: '0'
description: The team identifier
components:
securitySchemes:
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Email:
type: object
properties:
id:
type: string
sender:
type: object
properties:
id:
type: string
display_name:
type: string
email:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
inbox:
type: object
properties:
id:
type: string
display_name:
type: string
email:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
carbon_copies:
type: array
items:
type: object
properties:
display_name:
type: string
email:
type: string
subject:
type: string
created_at:
type: string
format: date-time
read:
type: string
format: date-time
favorite:
type: boolean
has_html:
type: boolean
has_text:
type: boolean
size_in_bytes:
type: integer
attachments:
type: array
items:
type: object
properties:
id:
type: string
email_id:
type: string
headers_hashed:
type: string
file_name:
type: string
content_type:
type: string
size_in_bytes:
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
size_for_human:
type: string
Statistics:
type: object
properties:
created_at:
type: string
format: date
emails_received:
type: integer
inboxes_created:
type: integer
storage_used:
type: integer
cumulative_storage_used:
type: integer
emails_deleted:
type: integer
Automation:
type: object
properties:
id:
type: string
title:
type: string
sender:
type: string
inbox:
type: string
subject:
type: string
has_attachments:
type: boolean
action_url:
type: string
action_secret_token:
type: string
notification_email:
type: string
format: email
nullable: true
disabled:
type: boolean
payload_format:
type: string
action_delete_email:
type: boolean
emails_received:
type: integer
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
paths:
/emails:
get:
summary: List emails
tags:
- Emails
parameters:
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: limit
in: query
required: false
schema:
type: integer
default: 25
- name: inbox
in: query
required: false
schema:
type: string
- name: sender
in: query
required: false
schema:
type: string
- name: subject
in: query
required: false
schema:
type: string
- name: since
in: query
required: false
schema:
type: string
format: date-time
- name: until
in: query
required: false
schema:
type: string
format: date-time
- name: search
in: query
required: false
schema:
type: string
- name: unread
in: query
required: false
schema:
type: boolean
- name: favorite
in: query
required: false
schema:
type: boolean
responses:
'200':
description: Successful response
content:
application/vnd.mailcare.v1+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Email'
links:
type: object
properties:
first:
type: string
last:
type: string
prev:
type: string
next:
type: string
meta:
type: object
properties:
current_page:
type: integer
from:
type: integer
last_page:
type: integer
path:
type: string
per_page:
type: integer
to:
type: integer
total:
type: integer
security:
- bearer_auth: []
/emails/{id}:
delete:
summary: Delete email
tags:
- Emails
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
security:
- bearer_auth: []
get:
summary: Get email (json, html or text content, raw)
tags:
- Emails
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: "Successful response. The response format depends on the `Accept` header you include in your request. Choose the header value that matches the format you want."
content:
application/vnd.mailcare.v1+json:
schema:
description: "JSON representation of the email. Set `Accept: application/vnd.mailcare.v1+json` to receive this format."
type: object
properties:
data:
$ref: '#/components/schemas/Email'
text/plain:
schema:
description: "Plain text body of the email. Set `Accept: text/plain` to receive this format."
type: string
example: |
Welcome to mailcare.io.
Follow this link to continue: https://mailcare.io
text/html:
schema:
description: "HTML body of the email. Set `Accept: text/html` to receive this format."
type: string
example: |
Welcome to mailcare.io
Follow this link to continue mailcare.io
message/rfc2822:
schema:
description: "Raw email including headers and attachments. Set `Accept: message/rfc2822` to receive this format."
type: string
example: |
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
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
this is html part
--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--
security:
- bearer_auth: []
/emails/{id}/attachments/{attachmentId}:
get:
summary: Get attachment
tags:
- Emails
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: attachmentId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/pdf:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
text/plain:
schema:
type: string
example: "simple content"
application/octet-stream:
schema:
type: string
format: binary
security:
- bearer_auth: []
/emails/{id}/favorites:
post:
summary: Favorite an email
tags:
- Emails
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
security:
- bearer_auth: []
delete:
summary: Unfavorite an email
tags:
- Emails
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
security:
- bearer_auth: []
/statistics:
get:
summary: List statistics
tags:
- Statistics
responses:
'200':
description: Successfully retrieved statistics.
content:
application/vnd.mailcare.v1+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Statistics'
meta:
type: object
properties:
emails_received:
type: integer
inboxes_created:
type: integer
storage_used_for_human:
type: string
storage_used:
type: integer
total_space:
type: integer
emails_deleted:
type: integer
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. Insufficient permissions.
security:
- bearer_auth: []
/automations:
get:
summary: List automations
tags:
- Automations
responses:
'200':
description: Successfully retrieved automations.
content:
application/vnd.mailcare.v1+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Automation'
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. Insufficient permissions.
security:
- bearer_auth: []
post:
summary: Create automation
tags:
- Automations
description: |
Creates a new automation that triggers an action when an email matching
the specified criteria is received.
requestBody:
required: true
content:
application/vnd.mailcare.v1+json:
schema:
type: object
required:
- title
properties:
title:
type: string
description: Title of the automation
example: "Save pdf invoices"
sender:
type: string
format: email
description: Sender that should match (optional)
example: "shop@example.com"
inbox:
type: string
format: email
description: Inbox that should match (optional)
example: "claire@example.com"
subject:
type: string
description: Subject that should match (optional)
example: "New invoice"
has_attachments:
type: boolean
description: Email should have at least one attachment (optional)
example: true
action_url:
type: string
format: uri
description: URL that will be called (optional)
example: "https://example.com/webhooks/save-pdf-invoices"
action_secret_token:
type: string
description: Use this token to validate received payloads (optional)
example: "SECRET12345$"
notification_email:
type: string
format: email
nullable: true
description: Email address to notify on webhook failures (optional). If empty, no notification is sent. At most one notification is sent per automation per UTC day.
example: "ops@example.com"
action_delete_email:
type: boolean
description: Email should be deleted after processing (optional)
example: true
disabled:
type: boolean
description: Disable this automation without deleting it (optional)
example: false
payload_format:
type: string
description: Payload format to use (optional)
enum: ["json", "raw", "json_with_bodies"]
example: "json"
responses:
'201':
description: Automation successfully created.
'400':
description: Bad request. Invalid input data.
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. Insufficient permissions.
security:
- bearer_auth: []
/automations/{id}:
put:
summary: Update automation
tags:
- Automations
description: Updates an existing automation with new parameters.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier of the automation to update.
requestBody:
required: true
content:
application/vnd.mailcare.v1+json:
schema:
type: object
required:
- title
properties:
title:
type: string
description: Title of the automation
example: "Save pdf invoices"
sender:
type: string
format: email
description: Sender that should match (optional)
example: "shop@example.com"
inbox:
type: string
format: email
description: Inbox that should match (optional)
example: "claire@example.com"
subject:
type: string
description: Subject that should match (optional)
example: "New invoice"
has_attachments:
type: boolean
description: Email should have at least one attachment (optional)
example: true
action_url:
type: string
format: uri
description: URL that will be called (optional)
example: "https://example.com/webhooks/save-pdf-invoices"
action_secret_token:
type: string
description: Use this token to validate received payloads (optional)
example: "SECRET12345$"
notification_email:
type: string
format: email
nullable: true
description: Email address to notify on webhook failures (optional). If empty, no notification is sent. At most one notification is sent per automation per UTC day.
example: "ops@example.com"
action_delete_email:
type: boolean
description: Email should be deleted after processing (optional)
example: true
disabled:
type: boolean
description: Disable this automation without deleting it (optional)
example: false
payload_format:
type: string
description: Payload format to use (optional)
enum: ["json", "raw", "json_with_bodies"]
example: "json"
responses:
'200':
description: Automation successfully updated.
'400':
description: Bad request. Invalid input data.
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. Insufficient permissions.
'404':
description: Not Found. The specified automation does not exist.
security:
- bearer_auth: []
delete:
summary: Delete automation
tags:
- Automations
description: Deletes an existing automation by its unique identifier.
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier of the automation to delete.
responses:
'204':
description: Automation successfully deleted.
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. Insufficient permissions.
'404':
description: Not Found. The specified automation does not exist.
security:
- bearer_auth: []