v5.10.2

This release of the Nylas Python SDK brings a singular change.

Release Notes

Changed

• Update package setup to be compatible with PEP 517 (#235)

New Contributors 🎉

• @aburgel made their first contribution in #235

v5.10.1

This release of the Nylas Python SDK brings a singular fix.

Release Notes

Fixed

• Fix authentication for integrations (#233)

v5.10.0

This release of the Nylas Python SDK brings a few additions.

Release Notes

Added

• Add metadata field to JobStatus (#227)
• Add missing hosted authentication parameters (#229)
• Add support for calendar field in free-busy, availability, and consecutive availability queries (#228)

Using New Features

New calendars field in free-busy/availability queries

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

# Free busy with calendars
start_time = datetime.now()
end_time = datetime.now() + timedelta(hours = 24)
calendars = [{
  "account_id": "test_account_id",
  "calendar_ids": ["example_calendar_a", "example_calendar_b"]
}]

free_busy = nylas.free_busy("your_email@example.com", start_time, end_time, calendars)

# Availability with calendars
emails = ["one@example.com", "two@example.com", "three@example.com"]
start_time = datetime.now()
end_time = datetime.now() + timedelta(hours = 24)
duration = timedelta(minutes=30)
interval = timedelta(hours=1, minutes=30)
calendars = [{
  "account_id": "test_account_id",
  "calendar_ids": ["example_calendar_a", "example_calendar_b"]
}]

api_client.availability(emails, duration, interval, start_at, end_at, calendars=calendars)

# Consecutive availability with calendars
emails = [["one@example.com"], ["two@example.com", "three@example.com"]]
start_time = datetime.now()
end_time = datetime.now() + timedelta(hours = 24)
duration = timedelta(minutes=30)
interval = timedelta(hours=1, minutes=30)
calendars = [{
  "account_id": "test_account_id",
  "calendar_ids": ["example_calendar_a", "example_calendar_b"]
}]

api_client.consecutive_availability(emails, duration, interval, start_at, end_at, calendars=calendars)

New Contributors

• @kraju3 made their first contribution in #229

v5.9.2

This release of the Nylas Python SDK brings a small change.

Release Notes

Changed

• Add enforce_read_only parameter to overriding as_json functions (#225)

v5.9.1

This release of the Nylas Python SDK brings a few enhancements.

Release Notes

Added

• Add option to include read only params in as_json (#222)

Changed

• Change config file in hosted-oauth example to match new Flask rules (#221)

Fixed

• Fix unauthorized error for revoke_token (#223)

New Contributors 🎉

• @erikkai made their first contribution in #221
• @mkgs made their first contribution in #223

v5.9.0

This new release of the Nylas Python SDK brings support for collective and group events.

Release Notes

Added

• Support collective and group events

v5.8.0

This new release of the Nylas Python SDK brings a few changes.

Release Notes

Added

• Add support for getting the number of queried objects (count view)

Changed

• Improved usage of read only fields in models (fixes #212)

Fixed

• Fix Calendar availability functions not using the correct authentication method

Using New Features

Getting the number of queried objects (count view)

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

total_contacts = nylas.contacts.count()

# We also support filtering in conjunction with count
emails_from_support = nylas.messages.where(from_="support@nylas.com").count()

v5.7.0

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

Release Notes

Added

• Add Outbox support
• Add support for new (beta) Integrations authentication (Integrations API, Grants API, Hosted Authentication for Integrations)
• Add support for limit and offset for message/thread search
• Add authentication_type field to Account

Changed

• Bump supported API version to v2.5

Fixed

• Fix Draft not sending metadata (#205)

Using New Features

Outbox

To send a new message through the outbox:

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

# Create a draft
draft = api_client.drafts.create()
draft.subject = "With Love, from Nylas"
draft.to = [{"email": "test@email.com", "name": "Me"}]
draft.body = "This email was sent using the Nylas email API. Visit https://nylas.com for details."

# Set the outbox-specific parameters
tomorrow = datetime.datetime.today() + datetime.timedelta(days=1)
day_after = tomorrow + datetime.timedelta(days=1)

# Send the outbox message
job_status = nylas.outbox.send(draft, tomorrow, retry_limit_datetime=day_after)

To update an outbox message after sending it

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

# Modify the message
draft = nylas.drafts.get('{id}')
draft.subject = "With Love, from Nylas"

# Set the outbox-specific parameters
tomorrow = datetime.datetime.today() + datetime.timedelta(days=1)
day_after = tomorrow + datetime.timedelta(days=1)

# Update the outbox message
job_status = nylas.outbox.update("job-status-id", draft=draft, send_at=tomorrow, retry_limit_datetime=day_after)

To delete an outbox job

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

nylas.outbox.delete("job-status-id")

We also support SendGrid operations. To get the authentication and verification status

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

verification = nylas.outbox.send_grid_verification_status()
verification.domain_verified
verification.sender_verified

To delete a SendGrid user:

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

nylas.outbox.delete_send_grid_sub_user("test@email.com")

Integration Authentication (Beta)

Integrations API

To list all integrations:

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

all_integrations = nylas.authentication.integrations.list()

To get an integration for a specific OAuth Provider:

from nylas import APIClient
from nylas.client.authentication_models import Authentication
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

integration = nylas.authentication.integrations.get(Authentication.Provider.ZOOM)

To create a new integration (we will use Zoom for example):

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

integration = nylas.authentication.integrations.create()
integration.name("My Zoom Intrgration")
integration.set_client_id("zoom.client.id")
integration.set_client_secret("zoom.client.secret")
integration.redirect_uris = ["https://www.nylas.com"]
integration.expires_in(1209600)
integration.save()

To update an existing integration:

from nylas import APIClient
from nylas.client.authentication_models import Authentication
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

zoom_integration = nylas.authentication.integrations.get(Authentication.Provider.ZOOM)
zoom_integration.name = "Updated name"
zoom_integration.save()

To delete an existing integration for a specific OAuth provider:

from nylas import APIClient
from nylas.client.authentication_models import Authentication
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

nylas.authentication.integrations.delete(Authentication.Provider.ZOOM);

Grants

To list all grants:

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

all_grants = nylas.authentication.grants.list()

To get a specific grant:

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

grant = nylas.authentication.grants.get("grant-id")

To create a new grant (we will use Zoom for example):

from nylas import APIClient
from nylas.client.authentication_models import Authentication
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

grant = nylas.authentication.grants.create()
grant.provider = Authentication.Provider.ZOOM
grant.settings = {"refresh_token": "zoom_refresh_token"}
grant.state = "test_state"
grant.scope = ["meeting:write"]
grant.metadata = {"sdk": "python sdk"}
grant.save()

To update an existing grant:

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

grant = nylas.authentication.grants.get("grant-id")
grant.metadata = {"sdk": "python sdk"}
grant.save()

To delete an existing grant:

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

nylas.authentication.grants.delete("grant_id");

To trigger a re-sync on a grant:

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

resyced_grant = nylas.authentication.grants.on-demand-sync("grant_id",  sync_from=60);

Hosted Authentication for Authentication

To begin the hosted authentication process and get a login url:

from nylas import APIClient
from nylas.client.authentication_models import Authentication
nylas = APIClient(
    CLIENT_ID,
    CLIENT_SECRET,
    ACCESS_TOKEN
)

login_info = nylas.authentication.hosted_authentication(
  provider=Authentication.Provider.ZOOM,
  redirect_uri="https://www.nylas.com",
  settings={"refresh_token": "zoom_refresh_token"},
  scope=["meeting:write"],
  metadata={"sdk": "python sdk"},
  login_hint="example@mail.com",
  state="my-state",
  expires_in=43200
)

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"

v5.5.1

This patch release of the Nylas Python SDK contains two minor enhancements.

Enhancements

• Add validation for send_authorization (#194)
• Fix native-authentication-gmail example app (#192)