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.

Error Handling:


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


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


  • Object Information:

    • Webhooks contain full object information, reducing the need to fetch the object in many cases.
  • Empty attributes in webhooks
  • 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.
  • 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

Messages / Sending

  • 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 use V2 message_id as the reply_to_message value if your apps are linked.
  • 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


  • GMAIL Specific:
    • The first message_id is equal to the thread_id (ensure you record the object type so that you can differentiate).


  • Folder NAME vs ID:
    • Maintain a local database with folder NAME vs ID. There is no lookup to translate folder names to IDs on /message or /threads endpoints.
    • Either lookup the /folders endpoint to get the ID before making the call to the relevant object or store this locally.
    • We also have folder.* webhooks to allow you to keep your local DB updated on changes


  • Contact Webhooks:
    • We only support contact.updated, which is also triggered on creation. Enable this webhook via the API, not on the dashboard (currently).

Common Questions

Q: How do I relate V2 object IDs to new V3 objects?

  • A: We have an endpoint that provides V2 to V3 translation.
  • A. We will allow V2 object ID's in API V3, will be live end July

Q: Is the pricing the same?

  • A: Yes, contracts from V2 and cost per account are the same.




V3 Upgrade process review - Nylas Documentation 

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



Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.