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