Issues and Differences During Migration from V2 to V3 - Best Practices

This document tracks issues and differences that customers have encountered while migrating from V2 to V3.

General Differences

• In V3, unlike V2, you should not need to GET the object. The core concept of V3 is that you can avoid this step, due to the feature-rich webhooks which contain all the data.
• Limits and quotas are much stricter as you are querying the provider directly.
• We recommend /send or /drafts using Content-Type: multipart/form-data  instead of Content-Type: application/json this allows for sending all emails irrespective of the attachment size.
• Objects are not returned in any specific order by the provider. Unlike API V2 where we ordered objects by the most recent when querying /threads they are now returned by the oldest. The solution is to handle this locally.
• We only sync the Primary calendar by default
•  

Error Handling:

• Handling Empty Body in message.created / object.created Webhooks

Accounts

• Grant IDs vs. Account IDs:

  • Grant IDs do not remain the same across account deletions. If you track accounts, use the email address instead of the Grant ID, which can change if that grant is deleted.
  • Grants are immediately deleted, unlike V2 accounts.

• White-labeling:

  • Included with all packages that have full and above support agreements.

• Sync State Tracking:

  • Simplified with grant_status, which is returned on all /grants endpoints. There are only two states: valid and invalid.

• Callback URIs:

  • Wildcards for callback_uris are not supported. Please use the state attribute.

Events

• Event Movement:

  • Moving an event between calendars does not trigger an event.created on the calendar it was moved to. It generates a single event.updated.

• Primary Calendar Sync:

  • By default, we only sync the primary calendar of an account. To disable this, go to Dashboard > App > Webhook Settings > Disable the feature.
• V3 - All Day Events from Google and Microsoft Span Two Days.

Webhooks

• Object Information:

  • Webhooks contain full object information, reducing the need to fetch the object in many cases.
• Empty attributes in webhooks
  • We provide no validation on provider attributes as such attributes can be null, examples include: TO / BODY - these are optional fields

• Webhook Timing:

  • Webhooks are sent from the moment the grant_status becomes valid. To sync older objects, fetch them via the GET /endpoints.
  • We retry webhooks 5 times over 72 hours.
  • Webhooks cannot be replayed. If objects are missed during this window, use the grant.expired and grant.valid webhooks as timestamps for your queries.
• Tracking label is limited to 255 characters.

• Webhook Source Attribute:

  • Indicates how the object was synced:
    • Realtime: via pubsubs or streams
    • Incremental: via a batch scheduled job on our side
• New Webhooks folder.* this will allow you to store a local DB with folder values.

Object IDs

• Identification:
  • We use provider IDs to identify objects except with IMAP, where we use the full Header Message IDs due to IMAP provider IDs typically being 4-digit incremental numbers.
• Local Copy Support:
  • If you already have a local copy of objects and wish to provide V3 object IDs on these objects, please see Object ID translation from V2 to V3.
  • We also have an endpoint for single object lookup.
• V2 to V3 ID Translation:
  • V2 object ID's will work in V3 endpoints, only on GET method (expected live in July), will continue to function one year after EOL of V2 in October
  • Metadata on V2 objects must be synced to a locally stored DB, we do not provide a migration option for metadata.

Messages / Sending

• GET /messages/{multiple objects}:

  • This API V2 feature is not supported in API V3, you need to make multiple requests instead of a single request for multiple messages.

• Reply Handling:

  • We use the from attribute of messages to determine which from to use when replying. If a customer uses aliases, populate this by passing it in the payload. This differs from V2, where the mail value was stored from the provider account object. As such you now need to define this value.
  • You can NOT change the subject of a reply
  • With Microsoft if replying you need to add an "RE" + {subject} subject payload.
  • With Google and IMAP the Subject must be identical

• RAW Messages:

  • Fetching or sending RAW messages is not supported. Instead, use the option fields=include_headers. We do not support sending RAW messages, however you can set customer headers.
• IMAP / Sync / Sending:
  • IMAP is synced every 10 minutes
  • A sent email may not appear as a message.created until 5 minutes after sending, please use the response from the POST /send endpoint if you wish to display this object immediately.
  • We recommend GMAIL or / Microsoft if you are looking for quicker sync times, these are providers that support push notifications.
• Attachments
  • These need to be uploaded on every request, you can not upload and reference an ID.
  • Sending attachments in API V3 less than 3MB via JSON
  • Sending attachments in API V3 larger than 3MB via multipart

Threads

• For most providers:
  • The first message_id is equal to the thread_id (ensure you record the object type so that you can differentiate).
• Threading behaviour in API V3

Folders

• folder.updated webhook
  • is only triggered if the name / structure changes, not on the count changing.
  • IMAP only triggers these for object LESS than 90 days old see IMAP limitations
• Enumerate Folder ID's
  • Folders have been reworked in API V3, which requires a redesign from V2
  • Please see this document for folder Best Practices 

Contacts

• Contact Webhooks:
  • We only support contact.updated, which is also triggered on creation. 

Limits / Offsets

These are now handled with cursors.

• No previous cursor

•  

  Not possible to paginate to next 50 responses as was possible with Offset 

Message Tracking

• Click tracking hyperlinks are designed to become inactive if the account or grant associated with them is deleted.

Resources

V3 Upgrade process review - Nylas Documentation 

How do I migrate my V2 organization, applications, accounts and objects to V3

Nylas v3 Migration APIs

Updated July 31, 2024 12:48