v5.6.0

This new release of the Nylas Python SDK a couple of new features and enhancements.

New Features

• Add Delta support
• Add Webhook support (#193)

Enhancements

• Omit None values from resulting as_json() object
• Enable Nylas API v2.4 support

Usage

Delta

To get the latest cursor:

from nylas import APIClient
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

cursor = nylas.deltas.latest_cursor()

To return a set of delta cursors since a specific cursor:

from nylas import APIClient
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

delta_response = nylas.deltas.since("{CURSOR}")

# The returned type is of Deltas
cursor_start = delta_response.cursor_start
cursor_end = delta_response.cursor_end
list_of_deltas = delta_response.deltas

# Deltas.deltas contains a list of Delta objects
delta = list_of_deltas[0]
delta_cursor = delta.cursor
delta_event = delta.event
delta_id = delta.id
delta_object = delta.object

# The enclosed Delta.attributes instantiates the object provided in the Delta (Contact, File, etc.)
delta_attributes = delta.attributes

# You can also pass in other optional arguments:
# view: string - This type of view to return within the delta objects
# include_types: string[] | string - The list of types to include in the query ('file', 'event', etc.)
# exclude_types: string[] | string - The list of types to exclude in the query ('file', 'event', etc.)

nylas.deltas.since(cursor, view="expanded", include_types=["event", "file"])

To stream for delta cursors since a specific cursor:

from nylas import APIClient
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

# By default, the streaming function will listen indefinitely until the connection drops
# and upon reaching the end it will return an array of delta objects captured

streamed_deltas = nylas.deltas.stream(cursor)

# Optionally, you can pass in a reference to a function that would be called on every Delta

def on_delta_received(delta):
    print(delta)

nylas.deltas.stream(cursor, callback=on_delta_received)

# Furthermore, you can pass in an argument for timeout if you want to cut off the stream after a certain number of seconds

nylas.deltas.stream(cursor, callback=on_delta_received, timeout=180)

# You can also pass in other optional arguments:
# view: string - This type of view to return within the delta objects
# include_types: string[] | string - The list of types to include in the query ('file', 'event', etc.)
# exclude_types: string[] | string - The list of types to exclude in the query ('file', 'event', etc.)

nylas.deltas.stream(cursor, callback=on_delta_received, view="expanded", include_types=["event", "file"])

To long-poll for delta cursors since a specific cursor:

from nylas import APIClient
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

# By default, the streaming function will listen until until the timeout is reached
# and upon reaching the end it will return a Deltas object

longpoll_deltas = nylas.deltas.longpoll(cursor, timeout=30) # timeout is in seconds

# Optionally, you can pass in a reference to a function that would be called when the Deltas response is returned

def on_deltas_received(deltas):
    print(deltas)

nylas.deltas.longpoll(cursor, callback=on_deltas_received)

# You can also pass in other optional arguments:
# view: string - This type of view to return within the delta objects
# include_types: string[] | string - The list of types to include in the query ('file', 'event', etc.)
# exclude_types: string[] | string - The list of types to exclude in the query ('file', 'event', etc.)

nylas.deltas.longpoll(cursor, callback=on_delta_received, view="expanded", include_types=["event", "file"])

Webhooks

To create a new webhook:

webhook = nylas.webhooks.create()
webhook.callback_url = "https://your-server.com/webhook"
webhook.triggers = ["message.created"]
webhook.state = "active"
webhook.save()

To get all webhooks:

webhooks = nylas.webhooks.all()

To get a specific webhook:

webhook = nylas.webhooks.get("{WEBHOOK_ID}")

To update a component:

webhook = nylas.webhooks.get("{WEBHOOK_ID}")
webhook.state = "inactive"
webhook.save()

To delete a component:

nylas.webhooks.delete("{WEBHOOK_ID}")

There are also two helper enums provided for Webhooks, Trigger and State:

# The available Webhook triggers:
Webhook.Trigger.ACCOUNT_CONNECTED = "account.connected"
Webhook.Trigger.ACCOUNT_RUNNING = "account.running"
Webhook.Trigger.ACCOUNT_STOPPED = "account.stopped"
Webhook.Trigger.ACCOUNT_INVALID = "account.invalid"
Webhook.Trigger.ACCOUNT_SYNC_ERROR = "account.sync_error"
Webhook.Trigger.MESSAGE_CREATED = "message.created"
Webhook.Trigger.MESSAGE_OPENED = "message.opened"
Webhook.Trigger.MESSAGE_UPDATED = "message.updated"
Webhook.Trigger.MESSAGE_LINK_CLICKED = "message.link_clicked"
Webhook.Trigger.THREAD_REPLIED = "thread.replied"
Webhook.Trigger.CONTACT_CREATED = "contact.created"
Webhook.Trigger.CONTACT_UPDATED = "contact.updated"
Webhook.Trigger.CONTACT_DELETED = "contact.deleted"
Webhook.Trigger.CALENDAR_CREATED = "calendar.created"
Webhook.Trigger.CALENDAR_UPDATED = "calendar.updated"
Webhook.Trigger.CALENDAR_DELETED = "calendar.deleted"
Webhook.Trigger.EVENT_CREATED = "event.created"
Webhook.Trigger.EVENT_UPDATED = "event.updated"
Webhook.Trigger.EVENT_DELETED = "event.deleted"
Webhook.Trigger.JOB_SUCCESSFUL = "job.successful"
Webhook.Trigger.JOB_FAILED = "job.failed"

# The available Webhook states:
Webhook.State.ACTIVE = "active"
Webhook.State.INACTIVE = "inactive"