Managing folder in API V3

Folders in API V3 are returned in different formats for different providers, as a developer you need to build a method to handle these responses and ensure you do not hit provider limits in the eprocess.

Best practices: For IMAP and especially Microsoft we recommend GET /folders to populate a local database to allow for quick folder resolution then rely on folder.updated webook to keep the values updated.

It is not realistic to make API calls on every message to resolve the folder name, this will run into provider MailboxConcurrency limits.

GMAIL folder names are ENUMERATED

• Webook and Endpoint example of folder structure:
• Received email:

              "folders": [
                  "UNREAD",
                  "CATEGORY_PERSONAL",
                  "INBOX"
              ],

• Email moved to trash:
  

          "folders": [
              "TRASH",
              "CATEGORY_PERSONAL"
          ],

   

Microsoft folder names are a long RANDOM STRING

• Handling Microsoft folders is complicated as the webhook and message object return a long string that you need to then resolve via GET /folders to enumerate the id a readable name.

• Webook and Endpoint example of folder structure:

              "folders": [
                  "AQMkADAwATZiZmYAZC0xMQA1OC03MzMANC0wMAItMDAKAC4AAAOoZrYlCxBbT52CozufVpzRAQAZ3K3PJNE7Sp2lA9B5YqnHAAACAQwAAAA="
              ],

• Important: When calling the GET /folders endpoint we only return the top two levels for Microsoft accounts, if you wish to retrieve all the folders:
• Workflow:
  • GET /folders
  • IF child_count > 0 AND parent_id EXISTS
  • GET /folder/id
    • FOR loop through all the folders to build the structure.

IMAP folder names are provider specific

• Every provider has a different format however they typically follow the following structure:

• Webook and Endpoint example of folder structure:

              "folders": [
                  "v0:d879d4fd-69e5-4335-8c7b-0cf56c84d915:INBOX",
                  "v0:d879d4fd-69e5-4335-8c7b-0cf56c84d915:INBOX.Sent"
              ],

• You can either provide the regex to parse the folder name directly from the response or follow the same process as with Microsoft of translating these id values to a readable name

Resources

Folders Documentationn

Updated July 11, 2024 18:07