Email API Docs

Introduction to the Email API

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can begin making requests to the Email API endpoints listed below.

Here are the supported services, listed with service identifiers:

Email Services
- Gmail: gmail
- Microsoft Outlook Mail: outlook_email
  - Both consumer Outlook as well as Office 365
- Microsoft Exchange Server 2007+: exchange_email
  - Features vary by Exchange Server version
- IMAP/SMTP: imap (Alpha release)

The Email API includes the following object types:

message
label
folder

Each object type is documented below, with its standard Kloudless attributes listed.

Kloudless object attributes that are absent in the upstream service will be null when retrieved, and ignored when sent in create/update requests.

Quickstart

Gmail requires configuring Custom OAuth Keys prior to connecting any accounts. See our Gmail connector guide to learn how to get started with Gmail.

For other connectors such as Outlook and Exchange Server, feel free to use our API Explorer to connect an account and test out API requests based on our documentation below.

Messages

A Message object represents an individual email message’s metadata.

id Unique identifier for the message.
created ISO 8601 timestamp indicating when the message was created.
thread_id The ID of the thread the messages belong to
folder_id The ID of the folder containing these messages. Only supported for outlook_email and exchange_email
labels A list of Label objects, each representing a label the message was tagged with.
subject The subject of the message.
from A Person object describing the sender.
to A list of Person objects describing the recipients.
cc A list of Person objects who are cc’d as recipients.
bcc A list of Person objects who are bcc’d as recipients.
snippet The snippet represents a short preview of the message text.
text_body The plain-text of the message body.
body The full HTML message body. Messages with only plain-text representations have this body attribute set to their plain-text content wrapped within an HTML pre tag when retrieving message data.
- If displaying this content on a web page, we recommend rendering the content within an iframe on a separate domain to avoid the parent page’s styling from impacting the HTML email body, and to also avoid script injection or other security concerns with unsafe HTML content. Outlook documents that its API returns safe HTML, although other connectors return the original HTML in the email.
rfc822 A File object containing the raw message content. The mime_type of RFC 822 format email will always be message/rfc822 and the name will always be raw_content.rfc822. Raw content will generally not be sanitized unless done by the upstream service (e.g. outlook_email, exchange_email).
attachments A list of File objects, each representing an individual attachment included in the message.
raw The raw object retrieved from the upstream email service’s API.
type Always message.
api Always email.

Person objects have the following structure:

email Email address of the person.
name Name of the person.
type Always person.
api Always email.

The file-type objects in the response representing RFC 822 content and attachments can be used in the following Storage API endpoints:

Download a File: Downloads the mail or attachment content.
Retrieve File Metadata: Retrieves a metadata object representing the mail content or an attachment’s content.

List Messages

List MessagesGET /accounts/{account_id}/email/messages/{?page,page_size,folder_id,thread_id,labels,after,before}

This endpoint enables you to retrieve messages from the user’s mailbox. By default, all mail in the user’s mailbox, including various labels or folders in the account, is retrieved. Review the query parameters supported for more information on retrieving messages specific to a folder, label, thread, or filtering for mail within a certain time range.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/messages/'

Page sizes requested are treated as advisory. Behavior varies by service:

Gmail returns at most 100 messages per page.
Our Exchange Server connector does not currently support paginating through messages.
Outlook and IMAP attempt to return the requested page size.

The response contains the following information, where each object is a Message:

count Integer. Number of objects on this page.
page String. Page identifier.
next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.
objects Array. List of objects.

Parameters
before
string (optional)
Only events created before this ISO 8601 timestamp (exclusive) are returned. The default value is the current time.

after
string (optional)
Only messages created at or after this ISO 8601 timestamp (inclusive) are returned. The default value is three days prior to the before parameter value.

folder_id
string (optional)
The ID of the folder containing these messages. Only supported for outlook_email and exchange_email. gmail uses labels to represent IMAP mail folders instead.

thread_id
string (optional)
The ID of the thread the messages belong to. Supported for gmail, outlook_email, exchange_email.

labels
string (optional)
The name(s) of the labels the message is tagged with. Multiple labels can be included in the query parameter to filter for messages tagged with all the specified labels. For example, to retrieve messages tagged with both label1 and label2, the querystring should be labels=label1&labels=label2. Please URL-encode the label names to avoid characters that may interfere with parsing the querystring. Supported for gmail, outlook_email, and exchange_email. Note that filtering by label in Outlook will result in all other filters being ignored, including time range.

page_size
number (optional) Default: 100
Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "message_MTcxMDkwMzFiMGU4ODJiNg",
      "thread_id": "thread_MTcxMDkwMzFiMGU4ODJiNg",
      "folder_id": null,
      "labels": [
        {
          "id": "label_VU5SRUFE",
          "name": "UNREAD",
          "type": "label",
          "api": "email"
        },
        {
          "id": "label_U0VOVA",
          "name": "SENT",
          "type": "label",
          "api": "email"
        },
        {
          "id": "label_SU5CT1g",
          "name": "INBOX",
          "type": "label",
          "api": "email"
        }
      ],
      "subject": "example email",
      "snippet": "example email description",
      "created": "2020-03-23T20:08:50Z",
      "type": "message",
      "api": "email",
      "to": [
        {
          "email": "receiver@company.com",
          "name": "receiver",
          "type": "person",
          "api": "email"
        }
      ],
      "cc": [],
      "bcc": [],
      "text_body": "example email description",
      "body": "<pre>example email description</pre>",
      "attachments": [],
      "rfc822": {
        "api": "storage",
        "type": "file",
        "id": "file_eyJpZCI6ICIxNzEwOTA",
        "mime_type": "message/rfc822",
        "name": "raw_content.rfc822",
        "href": "https://api.kloudless.com/v1/accounts/123/storage/files/file_eyJpZCI6ICIxNzEwOTA"
      },
      "from": {
        "email": "sender@company.com",
        "name": null,
        "type": "person",
        "api": "email"
      }
    }
  ],
  "type": "object_list",
  "api": "email"
}

Search for Messages

Search for messagesGET /accounts/{account_id}/email/search{?q,page,page_size}

The search endpoint performs a keyword search using the email service’s search capabilities. Each email service has its own search query parameters and operators:

gmail: Supports the same query format as the Gmail search box. Please refer to this Gmail Support article for details.
outlook_email: Performs a search on message collections. By default, the search is carried out on the default search properties of from, subject, and body. Please refer to the Outlook docs for details.
exchange_email: Performs a search on the email message body with the querystring.
imap: This endpoint is not yet supported for IMAP.

The response contains the following information:

count Integer. Number of objects on this page.
page String. Page identifier.
next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.
objects Array. List of objects.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/search/?q=test'

Parameters
q
string (required)
The terms to search for, or the search query to run. When running a search query, each service has its own format. The query is directly provided to the upstream service.

page_size
number (optional) Default: 100
Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "message_MTcxMDkwMzFiMGU4ODJiNg",
      "thread_id": "thread_MTcxMDkwMzFiMGU4ODJiNg",
      "folder_id": null,
      "labels": [
        {
          "id": "label_VU5SRUFE",
          "name": "UNREAD",
          "type": "label",
          "api": "email"
        },
        {
          "id": "label_U0VOVA",
          "name": "SENT",
          "type": "label",
          "api": "email"
        },
        {
          "id": "label_SU5CT1g",
          "name": "INBOX",
          "type": "label",
          "api": "email"
        }
      ],
      "subject": "example email",
      "snippet": "example email description",
      "created": "2020-03-23T20:08:50Z",
      "type": "message",
      "api": "email",
      "to": [
        {
          "email": "receiver@company.com",
          "name": "receiver",
          "type": "person",
          "api": "email"
        }
      ],
      "cc": [],
      "bcc": [],
      "text_body": "example email description",
      "body": "<pre>example email description</pre>",
      "attachments": [],
      "rfc822": {
        "api": "storage",
        "type": "file",
        "id": "file_eyJpZCI6ICIxNzEwOTA",
        "mime_type": "message/rfc822",
        "name": "raw_content.rfc822",
        "href": "https://api.kloudless.com/v1/accounts/123/storage/files/file_eyJpZCI6ICIxNzEwOTA"
      },
      "from": {
        "email": "sender@company.com",
        "name": null,
        "type": "person",
        "api": "email"
      }
    }
  ],
  "type": "object_list",
  "api": "email"
}

Retrieve a Message

Retrieve a MessageGET /accounts/{account_id}/email/messages/{message_id}

This API endpoint retrieves metadata for an individual message when provided its ID.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/messages/message_MTcxNWNkMjkzNDEyYjAzNw'

Downloading Attachments

The file-type objects in the response representing RFC 822 content and attachments can be used in the following Storage API endpoints:

Download a File: Downloads the mail or attachment content.
Retrieve File Metadata: Retrieves a metadata object representing the mail content or an attachment’s content.

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "id": "message_MTcxMDkwMzFiMGU4ODJiNg",
  "thread_id": "thread_MTcxMDkwMzFiMGU4ODJiNg",
  "folder_id": null,
  "labels": [
    {
      "id": "label_VU5SRUFE",
      "name": "UNREAD",
      "type": "label",
      "api": "email"
    },
    {
      "id": "label_U0VOVA",
      "name": "SENT",
      "type": "label",
      "api": "email"
    },
    {
      "id": "label_SU5CT1g",
      "name": "INBOX",
      "type": "label",
      "api": "email"
    }
  ],
  "subject": "example email",
  "snippet": "example email description",
  "created": "2020-03-23T20:08:50Z",
  "type": "message",
  "api": "email",
  "to": [
    {
      "email": "receiver@company.com",
      "name": "receiver",
      "type": "person",
      "api": "email"
    }
  ],
  "cc": [],
  "bcc": [],
  "text_body": "example email description",
  "body": "<pre>example email description</pre>",
  "attachments": [],
  "rfc822": {
    "api": "storage",
    "type": "file",
    "id": "file_eyJpZCI6ICIxNzEwOTA",
    "mime_type": "message/rfc822",
    "name": "raw_content.rfc822",
    "href": "https://api.kloudless.com/v1/accounts/123/storage/files/file_eyJpZCI6ICIxNzEwOTA"
  },
  "from": {
    "email": "sender@company.com",
    "name": null,
    "type": "person",
    "api": "email"
  }
}

Send a Message

send a MessagePOST /accounts/{account_id}/email/messages/send

To send an email (Message), perform a POST request containing a JSON object with the following attributes:

to (required) A list of Person objects describing the recipients.
from (optional) The Person object describing the sender (only supported for outlook_email and exchange_email).
reply_to (optional) The ID of the message to reply to.
cc (optional) A list of Person objects who are cc’d as recipients.
bcc (optional) A list of Person objects who are bcc’d as recipients.
subject (required) The subject of the message.
text_body (optional) The plain-text body to be sent.
body (optional) HTML formatted body to be sent. Either text_body or body should be specified. text_body will be ignored if this is specified.
attachments (optional) A list of one or more key value pairs, each with the key id and the value set to the attachment’s File object id. To retrieve an attachment’s File id, upload a file with the parent_id field set to ephemeral. The response from this endpoint will contain the attachment’s File id.
- Currently only supported for gmail.
- See our Email API documentation for an example of how to send an email with attachments.
- Note that Kloudless only guarantees a retention period of up to 60 minutes for files uploaded to the ephemeral location.
tracking (optional)
Message opens and clicks can optionally be tracked if an object is provided in the tracking attribute. Include the following attributes in the object:
- opens: A boolean value indicating whether to track email open activity.
- clicks: A boolean value indicating whether to track clicks on links in the email.
- subscription_id: The ID of a valid Subscription that has the subscription type analytics. Create one if one doesn’t exist, and provide its ID here. Use the list activity endpoint, to retrieve click and open tracking data. For click tracking, the v2 Activity API also provides detailed information on the exact link clicked.
Additional details regarding click and open tracking:
- Open tracking relies on email clients to load a tracking pixel, so results may vary based on email client behavior.
- Tracking activity is available for up to one year after the message was originally sent, but links will continue to work beyond that time.
- Developers using this feature are responsible for complying with any laws or privacy regulations related to tracking open and click activity.

Person objects have the following structure:

email (required) Email address of the person.
name (optional) Name of the person.

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/messages/send/' \
    -XPOST -d '{
        "to": [
            {
                "email": "receiver@company.com",
                "name": "receiver"
            }
        ],
        "text_body": "example email description",
        "subject": "example email"
    }'

Sending email with attachments

First, upload the attachment using the Upload a file endpoint with the value of parent_id set to ephemeral. The File object id returned in the response will be used to identify the attachment when sending the email in the next step.

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/octet-stream' \
    -H 'X-Kloudless-Metadata: {"parent_id": "ephemeral", "name": "héllö.png"}' \
    'https://api.kloudless.com/v1/accounts/me/storage/files/' \
    --data-binary '@FILE_PATH'

Then, include the attachment’s File id from the first step’s response in the attachments attribute. attachments is a list of key value pairs with the key id and the value set to the attachment’s id, as shown below.

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/messages/send/' \
    -XPOST -d '{
        "to": [
            {
                "email": "receiver@company.com",
                "name": "receiver"
            }
        ],
        "text_body": "example email description",
        "subject": "example email with attachment", 
        "attachments": [{"id": "file_MTIz"}, {"id": "file_NDU2"}]
    }'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "to": [
    {
      "email": "receiver@company.com",
      "name": "receiver"
    }
  ],
  "text_body": "example email description",
  "subject": "example email"
}

Response 201Toggle

Body

{
  "id": "message_MTcxMDkwMzFiMGU4ODJiNg",
  "thread_id": "thread_MTcxMDkwMzFiMGU4ODJiNg",
  "folder_id": null,
  "labels": [
    {
      "id": "label_VU5SRUFE",
      "name": "UNREAD",
      "type": "label",
      "api": "email"
    },
    {
      "id": "label_U0VOVA",
      "name": "SENT",
      "type": "label",
      "api": "email"
    },
    {
      "id": "label_SU5CT1g",
      "name": "INBOX",
      "type": "label",
      "api": "email"
    }
  ],
  "subject": "example email",
  "snippet": "example email description",
  "created": "2020-03-23T20:08:50Z",
  "type": "message",
  "api": "email",
  "to": [
    {
      "email": "receiver@company.com",
      "name": "receiver",
      "type": "person",
      "api": "email"
    }
  ],
  "cc": [],
  "bcc": [],
  "text_body": "example email description",
  "body": "<pre>example email description</pre>",
  "attachments": [],
  "rfc822": {
    "api": "storage",
    "type": "file",
    "id": "file_eyJpZCI6ICIxNzEwOTA",
    "mime_type": "message/rfc822",
    "name": "raw_content.rfc822",
    "href": "https://api.kloudless.com/v1/accounts/123/storage/files/file_eyJpZCI6ICIxNzEwOTA"
  },
  "from": {
    "email": "sender@company.com",
    "name": null,
    "type": "person",
    "api": "email"
  }
}

Update a Message

update a MessagePATCH /accounts/{account_id}/email/messages/{message_id}

To update an email (Message), perform a PATCH request containing a JSON object with the following attributes:

label_names (optional): A list of label names.

Editing labels is currently supported for the following services:

gmail
outlook_email

Example request:

curl -XPATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/messages/message_MTcxMDkwMzFiMGU4ODJiNg' \
    -d '{
      "label_names": ["UNREAD", "CUSTOM_LABEL"]
    }'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "label_names": [
    "UNREAD",
    "INBOX",
    "SENT"
  ]
}

Response 200Toggle

Body

{
  "id": "message_MTcxMDkwMzFiMGU4ODJiNg",
  "thread_id": "thread_MTcxMDkwMzFiMGU4ODJiNg",
  "folder_id": null,
  "labels": [
    {
      "id": "label_VU5SRUFE",
      "name": "UNREAD",
      "type": "label",
      "api": "email"
    },
    {
      "id": "label_U0VOVA",
      "name": "SENT",
      "type": "label",
      "api": "email"
    },
    {
      "id": "label_SU5CT1g",
      "name": "INBOX",
      "type": "label",
      "api": "email"
    }
  ],
  "subject": "example email",
  "snippet": "example email description",
  "created": "2020-03-23T20:08:50Z",
  "type": "message",
  "api": "email",
  "to": [
    {
      "email": "receiver@company.com",
      "name": "receiver",
      "type": "person",
      "api": "email"
    }
  ],
  "cc": [],
  "bcc": [],
  "text_body": "example email description",
  "body": "<pre>example email description</pre>",
  "attachments": [],
  "rfc822": {
    "api": "storage",
    "type": "file",
    "id": "file_eyJpZCI6ICIxNzEwOTA",
    "mime_type": "message/rfc822",
    "name": "raw_content.rfc822",
    "href": "https://api.kloudless.com/v1/accounts/123/storage/files/file_eyJpZCI6ICIxNzEwOTA"
  },
  "from": {
    "email": "sender@company.com",
    "name": null,
    "type": "person",
    "api": "email"
  }
}

Labels

A Label object represents the metadata of a label that email messages can be tagged with.

id Unique identifier for the label.
name Display name of the label.
type Will always be label.
api Will always be email.

List Labels

list labelsGET /accounts/{account_id}/email/labels

This feature is currently supported for the following services:

gmail
outlook_email

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/labels'

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "label_Q0FURUdPUllfUEVSU09OQUw",
      "name": "CATEGORY_PERSONAL",
      "type": "label",
      "api": "email"
    }
  ],
  "type": "object_list",
  "api": "email"
}

Retrieve Label metadata

retrieve label metadataGET /accounts/{account_id}/email/labels/{label_id}

This feature is currently supported for the following services:

gmail
outlook_email
exchange_email

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/labels/label_VU5SRUFE'

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "id": "label_Q0FURUdPUllfUEVSU09OQUw",
  "name": "CATEGORY_PERSONAL",
  "type": "label",
  "api": "email"
}

Create a Label

create a labelPOST /accounts/{account_id}/email/labels

This feature is currently supported for the following services:

gmail
outlook_email

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/labels' \
    -d '{"name": "My label"}'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "name": "My label"
}

Response 201Toggle

Headers

Content-Type: application/json

Body

{
  "id": "label_Q0FURUdPUllfUEVSU09OQUw",
  "name": "CATEGORY_PERSONAL",
  "type": "label",
  "api": "email"
}

Update a Label

update a labelPATCH /accounts/{account_id}/email/labels/{label_id}

This feature is currently supported for the following services:

gmail

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/labels/label_VU5SRUFE' \
    -d '{"name": "Updated label"}'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "name": "Updated label"
}

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "id": "label_Q0FURUdPUllfUEVSU09OQUw",
  "name": "CATEGORY_PERSONAL",
  "type": "label",
  "api": "email"
}

Delete a Label

delete a labelDELETE /accounts/{account_id}/email/labels/{label_id}

This feature is currently supported for the following services:

gmail
outlook_email

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/email/labels/label_VU5SRUFE

Response 204

Folders

A Folder object represents metadata of a folder that email messages can be in. They are equivalent to IMAP mail folders.

id Unique identifier for the folder.
name Display name of the folder.
type Will always be folder.
api Will always be email.

gmail uses labels to represent IMAP mail folders rather than distinguishing between labels and folders, so the Folder API endpoints are not supported. Please use the Label API endpoints instead.

This feature is currently supported for the following services:

outlook_email
exchange_email

Creating, updating and deleting folders are only currently supported for outlook_email.

List Folders

list foldersGET /accounts/{account_id}/email/folders

Note: For outlook_email, only folders at the root level will be retrieved.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/folders'

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "folder_QUFNa0FEaG1aVFZpTVdNeU",
      "name": "Folder name",
      "type": "folder",
      "api": "email"
    }
  ],
  "type": "object_list",
  "api": "email"
}

Create a Folder

create a folderPOST /accounts/{account_id}/email/folders

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/folders' \
    -d '{"name": "Folder name"}'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "name": "Folder name"
}

Response 201Toggle

Headers

Content-Type: application/json

Body

{
  "id": "folder_QUFNa0FEaG1aVFZpTVdNeU",
  "name": "Folder name",
  "type": "folder",
  "api": "email"
}

Retrieve Folder metadata

retrieve folder metadataGET /accounts/{account_id}/email/folders/{folder_id}

This feature is currently supported for the following services:

outlook_email
exchange_email

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/email/folders/folder_QUFNa0FEaG1aVFZlV'

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "id": "folder_QUFNa0FEaG1aVFZpTVdNeU",
  "name": "Folder name",
  "type": "folder",
  "api": "email"
}

Update a Folder

update a folderPATCH /accounts/{account_id}/email/folders/{folder_id}

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/email/folders/folder_VU5SRUFE' \
    -d '{"name": "Folder name"}'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "name": "Folder name"
}

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "id": "folder_QUFNa0FEaG1aVFZpTVdNeU",
  "name": "Folder name",
  "type": "folder",
  "api": "email"
}

Delete a Folder

delete a folderDELETE /accounts/{account_id}/email/folders/{folder_id}

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/me/email/folders/folder_VU5SRUFE'

Response 204

Activity Monitoring

Monitor new, deleted, or moved/altered mail via Kloudless’ Activity Monitoring API.

We currently present the following types of activity as Kloudless Event objects:

add: a new object has been created
delete: an object has been deleted
update: an object has been modified

We currently only track modifications to Message objects.

See the Activity Monitoring API docs for more information on supported services, API endpoints, and the format of activity stream data.

Activity API required: These endpoints require your Kloudless subscription to include access to the Activity API.

List Activity

List ActivityGET /accounts/{account_id}/subscriptions/{subscription_id}/activity{?cursor}]

The response contains the following fields:

objects: List of the activity that has taken place. If no activity is available, then there are no objects left to paginate through using the cursor at this time.
cursor: A string identifying a location in the stream immediately after the activity described in objects.
count: Number of activity objects returned.
total: An optional field only present when Kloudless temporarily stores activity data for retrieval by an application. Represents the total number of activity objects currently stored for this account. Not present for connectors that directly query the upstream API for activity information. See Activity Retention for more information.
type: Will always be object_list.
api: Will always be activity.

The returned cursor should be used in subsequent requests so that only activity that has not been seen previously is returned.

Use the default alias to access the default Subscription’s activity as shown in this example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/default/activity?cursor=121'

Check out the full Activity Monitoring API docs for more information on the API response format.

Email API Docs

Introduction to the Email API

Quickstart

Messages

List Messages

Search for Messages

Retrieve a Message

Downloading Attachments ¶

Send a Message

Sending email with attachments ¶

Update a Message

Labels

List Labels

Retrieve Label metadata

Create a Label

Update a Label

Delete a Label

Folders

List Folders

Create a Folder

Retrieve Folder metadata

Update a Folder

Delete a Folder

Activity Monitoring

List Activity

Downloading Attachments

Sending email with attachments