# Email API

## Aurinko Email API

***

The Aurinko Email API abstracts away differences between popular email APIs (Gmail, Office 365, Outlook.com, MS Exchange, Zoho Mail, iCloud, IMAP) to make it easy to develop email integrations.

### Functionality

***

The Aurinko Email API provides a REST interface that focuses on accessing and syncing email messages in a uniform manner.

* Access data for email messages, such as email content, sender and recipient information, subject lines, dates, and more.
* Search email inboxes for specific content.
* Update the unread and flagged status of email messages.
* Manage and download file attachments.
* Create drafts and send emails.
* Incremental synchronization.

### Aurinko account setup

***

First, create your account in the [Aurinko portal](https://app.aurinko.io/), then follow the guide to [get your developer API keys](https://docs.aurinko.io/getting-started/get-your-developer-api-keys). To test with Google Workspace accounts review this article: [Adding Aurinko to Google Workspace allowlist](https://docs.aurinko.io/getting-started/adding-aurinko-to-google-workspace-allowlist).

### Email API Endpoints

***

#### **Email messages**

[Email messages](https://apirefs.aurinko.io/#tag/Messages) are the core building block for most email applications. They contain several pieces of information, such as when a message was sent, the sender's address, to whom it was sent, and the message body. They can also contain file attachments, calendar event invitations, and more.

#### **Synchronization**

[Email sync](https://apirefs.aurinko.io/#tag/EmailSync) methods allow developers to implement incremental synchronization of email messages in a uniform manner across different email providers. Aurinko supports requesting updated as well as deleted messages.

#### **Draft messages**

[Draft messages](https://apirefs.aurinko.io/#tag/Drafts) methods allow developers to create new drafts, read existing drafts, and send drafts.

#### **Email tracking**

[Email tracking](https://apirefs.aurinko.io/#tag/EmailTracking) methods allow developers to access and manage open and reply/bounce tracking data.

### Email sync quickstart

***

#### **Start a new sync**

A new sync needs to be provisioned by calling the "sync start" method <mark style="color:red;">`/messages/sync`</mark>. The sync covers all email folders (i.e. Inbox, Sent Mail, and sub folders). <mark style="color:red;">`daysWithin`</mark> limits the initial scan to emails received in the past <mark style="color:red;">`daysWithin`</mark> days.

```bash
curl -X POST -H 'Authorization: Bearer <account\_access\_token>'
    -G https:/api.aurinko.io/v1/email/sync[?awaitReady=false]
    -d daysWithin=10"
```

The Aurinko platform will initialize all necessary internal resources and let you know when it's ready to serve data. The response should look like this:

```json
{
    "syncUpdatedToken": "asdfghjklpoiuytrew",
    "syncDeletedToken": "zxcvbnmlkjhgfdsaq",
    "ready": true
}
```

If the response shows <mark style="color:red;">`ready: false`</mark> call the "sync start" method again. Once the sync is ready you will get delta tokens <mark style="color:red;">`syncUpdatedToken`</mark>, <mark style="color:red;">`syncDeletedToken`</mark> and can start loading updated and deleted email messages.

#### **Initial full sync**

Initial requests <mark style="color:red;">`/messages/sync/updated`</mark> and <mark style="color:red;">`/messages/sync/deleted`</mark> are equivalent to a full sync in the specified <mark style="color:red;">`timeMin`</mark>,<mark style="color:red;">`NOW`</mark> range, plus loading all updated messages (deleted messages) since the sync start.

```bash
curl -X GET -H 'Authorization: Bearer <access token>'
    -G https:/api.aurinko.io/v1/email/sync/updated
    -d deltaToken='{syncUpdatedToken}'
```

*Response:*

```json
{   
    "nextPageToken": "string",
    "nextDeltaToken": "string",
    "records": [{...}]
}
```

Continue loading pages using provided 'nextPageToken' until you find another 'nextDeltaToken'.

```bash
curl -X GET -H 'Authorization: Bearer <access token>'
    -G https:/api.aurinko.io/v1/email/sync/updated
    -d pageToken='{nextPageToken}'
```

#### **Incremental sync**

A new deltaToken (nextDeltaToken in a response) is provided for loading email messages that have been modified/deleted since the last sync-updated/sync-deleted request. In cases where a large number of messages have changed since the last incremental sync request, you may find a <mark style="color:red;">`nextPageToken`</mark> instead of the <mark style="color:red;">`nextDeltaToken`</mark> in the response. Continue loading pages using the provided <mark style="color:red;">`nextPageToken`</mark> until you find another <mark style="color:red;">`nextDeltaToken`</mark>.

### Other examples

***

#### Email Messages <a href="#email-messages" id="email-messages"></a>

To get a list of messages from, to, or cc'ing an email address, make a request to the <mark style="color:red;">`/email/messages`</mark> endpoint.

```bash
curl -X GET -H 'Authorization: Bearer <access token>'
    -G https:/api.aurinko.io/v1/email/messages
    -d q="text from:alexey"
```

To get an email message by id make a request to the <mark style="color:red;">`/email/messages/{id}`</mark> endpoint.

```bash
curl -X GET -H 'Authorization: Bearer <access token>'
    https:/api.aurinko.io/v1/email/messages/{id}  
```

***

#### Email Tracking Options <a href="#email-tracking-options" id="email-tracking-options"></a>

To enable email tracking, include the <mark style="color:red;">`tracking`</mark> object in the request body when sending a message via the <mark style="color:red;">`/email/messages`</mark> endpoint.

Tracking supports:

* **opens** — tracks when the recipient opens the email
* **threadReplies** — tracks replies within the same email thread
* **trackOpensAfterSendDelay** — delay in seconds before enabling opens tracking (default: 5)
* **context** — optional custom string returned in tracking events, useful for correlating emails with external entities
* **customDomainAlias** — optional custom domain for the tracking pixel URL (default: Aurinko’s domain)

When sending an email with HTML content and requiring returned message IDs, use the following endpoint and query parameters:

```
POST https://api.aurinko.io/v1/email/messages?bodyType=html
```

Example request with tracking enabled:

```bash
curl -H 'Authorization: Bearer <access token>'
    -X POST https:/api.aurinko.io/v1/email/messages?bodyType=html
    -d '{
      "subject": "re: product proposal",
      "tracking": {
          "opens": true,
          "threadReplies": true,
          "trackOpensAfterSendDelay": 10,
          "context": "Something I want to associate with this email",
          "customDomainAlias": "tracking.company.com"
      },
      "body": "Hello there!",
      "to": [
           {
               "address": "demo@aurinko.io"
           }
      ]
    }'
```

***

#### Search Email Messages using q <a href="#search-email-messages" id="search-email-messages"></a>

In the Aurinko API, you can filter email messages using the <mark style="color:red;">`q`</mark> query parameter. This parameter supports various search operators, allowing you to find messages by sender, recipient, subject, date, and other criteria. To use it, make a request to the <mark style="color:red;">`/email/messages`</mark> endpoint.\
Support may vary depending on the account type (Office365, Gmail, IMAP or EWS).

**Example request:**

```
GET https://asti.aurinko.io/v1/email/messages?q=from:user
```

The following query operators are supported in Aurinko:

| Operator        | Example                             | Description                                                       | Comments                                                                      |
| --------------- | ----------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `from:`         | `from:user`                         | Messages from a specific sender.                                  |                                                                               |
| `to:`           | `to:demo@aurinko.io`                | Messages sent to a recipient.                                     |                                                                               |
| `cc:`           | `cc:user@aurinko.io`                | Messages where recipient is in CC.                                |                                                                               |
| `bcc:`          | `bcc:user@aurinko.io`               | Messages where recipient is in BCC.                               |                                                                               |
| `subject:`      | `subject:test`                      | Search by subject text.                                           |                                                                               |
| text search     | `test email`                        | Search for messages containing specific words in subject or body. |                                                                               |
| `after:`        | `after:2025/06/15`                  | Messages sent after a specific date.                              | Partially supported — may depend on server type; IMAP/EWS support is limited. |
| `before:`       | `before:2025/06/15`                 | Messages sent before a specific date.                             | Partially supported — may depend on server type; IMAP/EWS support is limited. |
| `label:`        | `label:inbox`                       | Search by label.                                                  | Gmail only; not supported for IMAP/EWS.                                       |
| `rfc822msgid:`  | `rfc822msgid:200503292@example.com` | Search by internet message ID.                                    | Fully supported where message ID is available.                                |
| `recipients:`   | `recipients:demo@aurinko.io`        | Search by any recipient (To/Cc/Bcc).                              |                                                                               |
| `participants:` | `participants:user@aurinko.io`      | Search messages involving a participant.                          |                                                                               |
| `classifier:`   | `classifier:important`              | Custom message classifier.                                        | Supported where classifier is applied.                                        |
| `has:`          | `has:attachment`                    | Filter messages that have attachments or other elements.          | Fully supported where metadata is available.                                  |
| `is:`           | `is:read` / `is:unread`             | Filter by message status.                                         | Fully supported; in Office365 and EWS, use `-is:read` for unread messages.    |
| `larger:`       | `larger:10M`                        | Messages larger than specified size.                              | Supported; requires numeric value with optional unit.                         |
| `smaller:`      | `smaller:1M`                        | Messages smaller than specified size.                             | Supported; requires numeric value with optional unit.                         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aurinko.io/unified-apis/email-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.