Email API
Aurinko's Email API provides a RESTful interface for accessing and syncing email messages across popular providers like Gmail, Office 365, iCloud, etc.
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, then follow the guide to get your developer API keys. To test with Google Workspace accounts review this article: Adding Aurinko to Google Workspace allowlist.
Email API Endpoints
Email messages
Email 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 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 methods allow developers to create new drafts, read existing drafts, and send drafts.
Email tracking
Email tracking 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 /messages/sync
. The sync covers all email folders (i.e. Inbox, Sent Mail, and sub folders). daysWithin
limits the initial scan to emails received in the past daysWithin
days.
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:
{
"syncUpdatedToken": "asdfghjklpoiuytrew",
"syncDeletedToken": "zxcvbnmlkjhgfdsaq",
"ready": true
}
If the response shows ready: false
call the "sync start" method again. Once the sync is ready you will get delta tokens syncUpdatedToken
, syncDeletedToken
and can start loading updated and deleted email messages.
Initial full sync
Initial requests /messages/sync/updated
and /messages/sync/deleted
are equivalent to a full sync in the specified timeMin
,NOW
range, plus loading all updated messages (deleted messages) since the sync start.
curl -X GET -H 'Authorization: Bearer <access token>'
-G https:/api.aurinko.io/v1/email/sync/updated
-d deltaToken='{syncUpdatedToken}'
Response:
{
"nextPageToken": "string",
"nextDeltaToken": "string",
"records": [{...}]
}
Continue loading pages using provided 'nextPageToken' until you find another 'nextDeltaToken'.
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 nextPageToken
instead of the nextDeltaToken
in the response. Continue loading pages using the provided nextPageToken
until you find another nextDeltaToken
.
Other examples
Email messages
To get a list of messages from, to, or cc'ing an email address, make a request to the /email/messages
endpoint.
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 /email/messages/{id}
endpoint.
curl -X GET -H 'Authorization: Bearer <access token>'
https:/api.aurinko.io/v1/email/messages/{id}
To send a new email with tracking make a request to the /email/messages
endpoint.
curl -H 'Authorization: Bearer <access token>'
-X POST https:/api.aurinko.io/v1/email/messages
-d '{
"subject": "re: product proposal",
"tracking": {
"opens": true,
"threadReplies": true,
"context": "Something I want to associate with this email"
},
"body": "Hello there!",
"to": [
{
"address": "[email protected]"
}
]
}'
Search email messages using q
q
In the Aurinko API, you can filter email messages using the q
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 /email/messages
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:
from:
from:user
Messages from a specific sender.
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:[email protected]
Search by internet message ID.
Fully supported where message ID is available.
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.
Last updated