Manage Email Folders

Allow your users the flexibility to manage their email address with email folders

Email Folders

When an email address is provisioned through the Email SDK, a set of standard folders are also created and associated with the provisioned email address. The following table describes the standard folders:

Folder	Function
INBOX	Inbound messages are assigned to the INBOX folder.
SENT	Outbound messages which have completed sending are assigned to the SENT folder.
OUTBOX	Reserved for future use.
TRASH	Messages can be moved to the TRASH folder. Messages in this folder will automatically be deleted after a set period of time depending on the application's configuration.

Retrieving Email Folders

Email folders associated with an email address are available in the folders attribute of that email address and are retrieved along with the email address.

Email folders associated with an email address can also be retrieved directly through the listEmailFoldersForEmailAddressId method by passing in the id of the email address to query. This returns a ListOutput object with the list of email folder objects which contain information used to identify each folder and to facilitate moving of messages between folders.

The EmailFolder object contains useful information such as the name of the folder, the total size of all messages assigned to the folder and the total count of unseen messages assigned to the folder.

TypeScript

// Obtain the input email address id however makes sense for your implementation.
const emailAddressId = emailAddress.id
try {
    const listOutput = await emailClient.listEmailFoldersForEmailAddressId({
        emailAddressId,
        cachePolicy: CachePolicy.RemoteOnly,
        nextToken,
    })
    // `listOutput` contains the list of items matching the input. 
    // Page through the results if listOutput.nextToken != nil.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input email address id however makes sense for your implementation.
let emailAddressId = emailAddress.id
let input = ListEmailFoldersForEmailAddressIdInput(
    emailAddressId: emailAddressId,
    limit: 10,
    nextToken: nil
)
do {
    let output = try await emailClient.listEmailFoldersForEmailAddressId(
        withInput: input
    )
    // `output` contains the `ListOutput` of items matching the input.
    // `output.items` contains an array of `EmailFolder`
    // Page through the results if output.nextToken != undefined.
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the input email address id however makes sense for your implementation.
val emailAddressId = emailAddress.id
launch {
    try {
        val input = ListEmailFoldersForEmailAddressIdInput(
            emailAddressId = emailAddressId,
            limit = 10,
            nextToken = null
        )
        val listOutput = withContext(Dispatchers.IO) { 
            emailClient.listEmailFoldersForEmailAddressId(input)
        }
        // [listOutput] contains the [ListOutput] of items matching the input.
        // [listOutput.items] contains a list of [EmailFolder]s
        // Page through the results if listOutput.nextToken != null.
    } catch (e: EmailFolderException) {
        // Handle/notify user of exception
    }
}

Move Email Messages between Folders

Email messages can also be moved between folders. For example an email message stored in the "inbox" folder can be moved to the "trash" folder. This is done through the update email messages API as described here. The email message object contains a previousFolderId property which specifies the identifier of the folder that the message was previously in. An example implementation of using the updateEmailMessages method to move a message to another folder is:

TypeScript

// Obtain the input message ids and email address id however makes sense for your implementation.
const emailAddressId = emailAddress.id
const ids = ['message-id-1', 'message-id-2']
try {
   // List the email folders and find the "trash" folder.
   const trashFolder = await emailClient.listEmailFoldersForEmailAddressId({
     emailAddressId,
     cachePolicy: CachePolicy.RemoteOnly
   }).then((result) => result.items.find(folder) => folder.folderName === 'TRASH')
 
   // Update an email message using the "trash" folder id.
   await emailClient.updateEmailMessages({
        ids,
        values: { folderId: trashFolder.id },
    })
   // Each of the input messages should now be assigned to the "trash" folder.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input message ids and email address id however makes sense for your implementation.
let emailAddressId = emailAddress.id
let ids = ['message-id-1', 'message-id-2']
let input = ListEmailFoldersForEmailAddressIdInput(
    emailAddressId: emailAddressId,
    limit: 10,
    nextToken: nil
)
do {
    // List the email folders and find the "trash" folder.
    let output = try await emailClient.listEmailFoldersForEmailAddressId(
        withInput: input
    )
    let trashFolderIds = output.items.filter { $0.id.contains("TRASH") }
    guard let trashFolderId = trashFolderIds.first else {
        return
    }
    let input = UpdateEmailMessagesInput(
        ids: ids,
        values: UpdateEmailMessagesValues(
            folderId: trashFolderId,
            seen: true
        )
    ) 
    // Update the email messages using the "trash" folder id.
    let result = try await emailClient.updateEmailMessages(withInput: input)
    switch result {
    case .success:
        // All email messages assigned to the TRASH folder.
    case. partial:
        // `result.successItems` contains an array of all the email message IDs 
        // that were assigned to the TRASH folder successfully.
        // `result.failureItems` cotains an array of all the email message IDs
        // that failed to be assigned to the TRASH folder.
    case .failure:
        // All email messages failed to be assigned to the TRASH folder.
    }
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the input draft message ids and email address id however makes sense for your implementation.
val emailAddressId = emailAddress.id
val ids = listOf("message-id-1", "message-id-2")
launch {
    try {
        // List the email folders and find the "trash" folder.
        val listInput = ListEmailFoldersForEmailAddressIdInput(
            emailAddressId = emailAddressId,
            limit = 10,
            nextToken = null
        )
        val emailFoldersList = withContext(Dispatchers.IO) { 
            emailClient.listEmailFoldersForEmailAddressId(listInput)
        }
        val trashFolder = (emailFoldersList.filter { it.folderName == "TRASH" }).first()
        
        // Update the email messages using the "trash" folder id.
        val updateInput = UpdateEmailMessagesInput(
            ids = ids,
            values = UpdateEmailMessagesInput.UpdatableValues(folderId = trashFolder.id)
        )
        val result = withContext(Dispatchers.IO) {
            emailClient.updateEmailMessages(updateInput)
        }
        when (result) {
            is BatchOperationResult.SuccessOrFailureResult -> {
                // [result.status] contains the status of the batch update operation.
            }
            is BatchOperationResult.Partial -> {
                // [result.successValues] contains the list of items in which the update operation succeeded.
                // [result.failureValues] contains the list of items in which the update operation failed.
            }
        }
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

Creating Custom Email Folders

Users can create custom folders for whatever purpose suits them. These behave in much the same way as the standard folders. To create a custom email folder, call the createCustomEmailFolder method with the name of the custom folder and the id of the email address the folder should be associated with. Duplicate folder names will not be allowed. Once a folder has been created, messages can be moved in and out of them the same way as described above.

TypeScript

// Obtain the email address id however makes sense for your implementation.
const emailAddressId = emailAddress.id
const customFolderName = "Custom"
try {
   // Create a custom email folder
   const customFolder = await emailClient.createCustomEmailFolder({
        emailAddressId,
        customFolderName,
    })
   // The customEmailFolder will contain the newly created email folder and all of its metadata
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the email address id however makes sense for your implementation.
let emailAddressId = emailAddress.id
let input = CreateCustomEmailFolderInput(
    emailAddressId: emailAddress.id, 
    customFolderName: "Custom"
)
do {
    let customEmailFolder = try await client.createCustomEmailFolder(withInput: input)
    // The customEmailFolder will contain the newly created email folder and all of its metadat
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the email address id however makes sense for your implementation.
val emailAddressId = emailAddress.id
val input = CreateCustomEmailFolderInput(emailAddress.id, "Custom")
launch {
    try {
        val customEmailFolder = withContext(Dispatchers.IO) {
            emailClient.createCustomEmailFolder(input)
        }
        // The customEmailFolder will contain the newly created email folder and all of its met
    } catch (e: EmailFolderException) {
        // Handle/notify user of exception
    }
}

Deleting Custom Email Folders

Users can also delete any custom email folders they have created. The standard folders associated with the email address cannot be deleted. To delete a custom email folder, call the deleteCustomEmailFolder method with the id of the custom email folder and the id of its associated email address. The method will return a copy of the deleted folder, or nothing if the folder could not be found. When a custom email folder is deleted, any messages in that folder will be moved to the TRASH folder.

TypeScript

// Obtain the folder id and email address id however makes sense for your implementation.
const customFolderId = customEmailFolder.id
const emailAddressId = emailAddress.id
try {
   // Delete a custom email folder
   const customFolder = await emailClient.deleteCustomEmailFolder({
        emailFolderId: customFolderId,
        emailAddressId,
   })
   // The customEmailFolder will contain the deleted email folder or undefined
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the folder id and email address id however makes sense for your implementation.
let customFolderId = customEmailFolder.id
let emailAddressId = emailAddress.id
let input = DeleteCustomEmailFolderInput(
    emailFolderId: customFolderId, 
    emailAddressId: emailAddressId
)
do {
    let customEmailFolder = try await client.deleteCustomEmailFolder(withInput: input)
    // The customEmailFolder will contain the deleted email folder or nil
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the custom email folder id and email address id however makes sense for your implementation.
val customEmailFolderId = customEmailFolder.id
val emailAddressId = emailAddress.id
val input = DeleteCustomEmailFolderInput(customEmailFolderId, emailAddressId)
launch {
    try {
        val customEmailFolder = withContext(Dispatchers.IO) {
            emailClient.deleteCustomEmailFolder(input)
        }
        // The customEmailFolder will contain the deleted email folder or null
    } catch (e: EmailFolderException) {
        // Handle/notify user of exception
    }
}

Updating Custom Email Folders

Custom email folders can be updated via the updateCustomEmailFolder method. At this point, only the name of a custom folder can be updated.

TypeScript

// Obtain the folder id and email address id however makes sense for your implementation
const emailAddressId = emailAddress.id
const customFolderId = customFolder.id
try {
    const inputValues: CustomEmailFolderUpdateValuesInput = {
          customFolderName: "new-folder-name",
    }
    
    const updatedFolder = await emailClient.updateCustomEmailFolder({
        emailAddressId: emailAddressId,
        emailFolderId: customFolderId,
        values: inputValues,
    })
    // updatedFolder will contain the folder with its updated values
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the folder id and email address id however makes sense for your implementation.
let customFolderId = customEmailFolder.id
let emailAddressId = emailAddress.id
let inputValues = UpdateCustomEmailFolderValues(customFolderName: "new-folder-name")
let input = UpdateCustomEmailFolderInput(
    emailFolderId: customFolderId,
    emailAddressId: emailAddressId,
    values: inputValues
)
do {
    let updatedEmailFolder = try await client.updateCustomEmailFolder(withInput: input)
    // The updatedEmailFolder will contain the email folder with its updated values
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the custom email folder id and email address id however makes sense for your implementation.
val customEmailFolderId = customEmailFolder.id
val emailAddressId = emailAddress.id
val input = UpdateCustomEmailFolderInput(
    emailAddressId,
    customEmailFolderId,
    "new-folder-name"
)
launch {
    try {
        val updatedEmailFolder = withContext(Dispatchers.IO) {
            emailClient.updateCustomEmailFolder(input)
        }
        // The updatedEmailFolder will contain the email folder with its updated values
    } catch (e: EmailFolderException) {
        // Handle/notify user of exception
    }
}

Deleting All Messages In A Folder

All messages can be deleted from a folder at once by calling the deleteEmailMessagesForFolderId method. This will delete all the messages currently in the folder indicated. Because there could be a large number of messages, and it could take a significant amount of time to complete, this is done asynchronously. The method does not return any indication of the result of the deletions. Deletion can be confirmed via subscriptions, or polling the list message endpoints.

The method accepts a folder id, and an optional hardDelete parameter indicating what type of delete to perform, as indicated in the table below.

`hardDelete` value	Behaviour
true(default)	Messages are completely deleted and no longer appear in the users account anywhere.
false	Messages are moved to the user's TRASH folder.

Note: If the folder the messages are being deleted from is the user's TRASH folder, the hardDelete parameter is always treated as false .

TypeScript

// Obtain the folder id and email address id however makes sense for your implementation
const emailAddressId = emailAddress.id
const emailFolderId = emailFolder.id
try {
    const result = await emailClient.deleteMessagesForFolderId({
      emailAddressId: emailAddressId
      emailFolderId: emailFolderId,
      hardDelete: false,
    })
    // result will be the emailFolderId if the deletion process was initiated successfully
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the folder id and email address id however makes sense for your implementation.
let emailFolderId = emailFolder.id
let emailAddressId = emailAddress.id
let deleteMessagesForFolderIdInput = DeleteMessagesForFolderIdInput(
    emailFolderId: emailFolderId,
    emailAddressId: emailAddressId,
    hardDelete: false
)

do {
    let result = try await client.deleteMessagesForFolderId(withInput: deleteMessagesForFolderIdInput)
    // The result will be the emailFolderId if the deletion process was initiated successfully
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the folder id and email address id however makes sense for your implementation.
val emailAddressId = emailAddress.id
val emailFolderId = emailFolder.id
launch {
    try {
        val input = DeleteMessagesForFolderIdInput(
            emailFolderId = emailFolderId,
            emailAddressId = emailAddressId,
            hardDelete = false
        )
        val deleteOutput = withContext(Dispatchers.IO) { 
            emailClient.deleteMessagesForFolderId(input)
        }
    // The deleteOutput will be the emailFolderId if the deletion process was initiated successfully
    } catch (e: EmailFolderException) {
        // Handle/notify user of exception
    }
}