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 perform API 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.


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 thread ID the message belongs to.

  • folder_id The folder ID the message is in. 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 Will always be message.

  • api Will always be email.

Person objects have the following structure:

  • email Email address of the person.

  • name Name of the person.

  • type Will always be person.

  • api Will always be email.

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

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. For example, Gmail only returns pages with at most 50 messages each.

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

  • count Number of objects on this page

  • page 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 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) 

    Folder ID the messages are listed within. Only applicable for outlook_email and exchange_email. gmail uses labels to represent IMAP mail folders instead.

    thread_id
    string (optional) 

    Thread ID the messages are listed within.

    labels
    string (optional) 

    A Label name the message is tagged with. Include this query parameter once per label to filter for messages tagged with all labels included in this request. For example, to retrieve messages with both labels label1 and label2 set on them, the querystring should be labels=label1&labels=label2. Please URL-encode the label names to avoid characters that may interfere with parsing the querystring.

    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. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • 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 Number of objects on this page

  • page 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 List of objects

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/email/search/?q=test'
  • Parameters
  • q
    string (required) 

    The terms to search for, or 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. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • 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/123/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:

  • 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 with 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.

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/123/email/messages/send/' \
    -XPOST -d '{
        "to": [
            {
                "email": "receiver@company.com",
                "name": "receiver"
            }
        ],
        "text_body": "example email description",
        "subject": "example email"
    }'
  • 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"
      }
    }

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.

This feature is currently only supported for the following services:

  • gmail

  • outlook_email

  • exchange_email

Retrieve Label metadata 

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

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/email/labels/label_VU5SRUFE'
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

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

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.

This feature is currently only supported for the following services:

  • outlook_email

  • exchange_email

  • imap

gmail uses Labels to represent IMAP mail folders rather than distinguishing between Labels and Folders.

Retrieve Folder metadata 

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

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/email/folders/folder_QUFNa0FEaG1aVFZlV'
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

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

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 endpoints 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.

  • 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.