Manage Email Folders & Draft Email

Allow your users the flexibility to manage their inbox with email folders and save draft emails securely

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 (this does not permanently delete the message).

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,
    cachePolicy: .remoteOnly,
    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,
            cachePolicy = CachePolicy.REMOTE_ONLY,
            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: EmailMessageException) {
        // 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,
    cachePolicy: .remoteOnly,
    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,
            cachePolicy = CachePolicy.REMOTE_ONLY,
            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) {
            app.sudoEmailClient.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
    }
}

Draft Email Messages

The Email SDK also supports the notion of draft email messages. A separate set of APIs are available to handle the lifecycle of drafts.

Creating a Draft Email Message

To create and save a draft email message, call the createDraftEmailMessage method. This method takes in a rfc822Data input property which contains the email message content formatted under RFC 822 as well as the senderEmailAddressId input property which must match the identifier of the email addess from the from field in the RFC 822 data. A call to this method returns metadata of the saved draft. Draft email message data provides the ID of the draft and an updatedAt timestamp representing the last time the draft was saved.

TypeScript

// Obtain the input RFC 822 data and sender email address id however makes sense for your implementation.
const rfc822Data: ArrayBuffer = // ...
const senderEmailAddressId = senderEmailAddress.id
try {
    const draftMetadata = await emailClient.createDraftEmailMessage({
        rfc822Data,
        senderEmailAddressId,
    })
    // `draftMetadata` is the metadata associated with the saved
    // draft email message including the id you can use this to access or
    // update the draft.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input RFC 822 data and sender email address id however makes sense for your implementation.
let rfc822Data: Data = // ...
let senderEmailAddressId = senderEmailAddress.id
let input = CreateDraftEmailMessageInput(
    rfc822Data: rfc822Data,
    senderEmailAddressId: senderEmailAddressId
)
do {
    let draftMetadata = try await emailClient.createDraftEmailMessage(
        withInput: input
    )
    // `draftMetadata` is the `DraftEmailMessageMetadata` associated with the saved
    // draft email message including the id which you can use to access or
    // update the draft.
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the input RFC 822 data and sender email address id however makes sense for your implementation.
val rfc822Data: ByteArray = // ...
val senderEmailAddressId = senderEmailAddress.id
launch {
    try {
        val input = CreateDraftEmailMessageInput(
            rfc822Data = rfc822Data,
            senderEmailAddressId = senderEmailAddressId
        )
        val draftId = withContext(Dispatchers.IO) {
            emailClient.createDraftEmailMessage(input)
        }
        // [draftId] is the unique id of the draft that you can use to access 
        // or update the draft
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

Updating a Draft Email Message

Use the updateDraftEmailMessage method to update a previously created and saved draft email message. The input requires the id of the previously saved draft to perform the update. It is a requirement that the entire message content be replaced with an updated version as part of the rfc822Data input property. A call to this method returns the id of the draft that was updated which should match the id provided in the input.

TypeScript

// Obtain the input RFC 822 data, sender email address id and existing draft id however makes sense for your implementation.
const id: string = // ...
const rfc822Data: ArrayBuffer = // ...
const senderEmailAddressId = senderEmailAddress.id 
try {
    const draftMetadata = await emailClient.updateDraftEmailMessage({
        id,
        rfc822Data,
        senderEmailAddressId,
    })
    // `draftMetadata` is the metadata associated with the saved
    // draft email message including the id you can use this to access or
    // update the draft.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input RFC 822 data, sender email address id and existing draft id however makes sense for your implementation.
let id: String = // ...
let rfc822Data: Data = // ...
let senderEmailAddressId = senderEmailAddress.id
let input = UpdateDraftEmailMessageInput(
    id: id,
    rfc822Data: rfc822Data,
    senderEmailAddressId: senderEmailAddressId
)
do {
    let draftMetadata = try await emailClient.updateDraftEmailMessage(
        withInput: input
    )
    // `draftMetadata` is the `DraftEmailMessageMetadata` associated with the
    // updated draft email message including the id which you can use to access
    // or update the draft.
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the input RFC 822 data, sender email address id and existing draft id however makes sense for your implementation.
val id: String = // ...
val rfc822Data: ByteArray = // ...
val senderEmailAddressId = senderEmailAddress.id
launch {
    try {
        val input = UpdateDraftEmailMessageInput(
            id = id,
            rfc822Data = rfc822Data,
            senderEmailAddressId = senderEmailAddressId
        )
        val draftId = withContext(Dispatchers.IO) {
            emailClient.updateDraftEmailMessage(input)
        }
        // [draftId] is the unique id of the draft that you can use to access 
        // or update the draft
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

Deleting Draft Email Messages

Draft email messages can be deleted in batches using the deleteDraftEmailMessages method by passing in one or more draft message identifiers and the id of the email address associated with the drafts.

Draft email messages that have been deleted will no longer be available and all traces of the message data and metadata will be deleted permanently.

Draft email messages can only be deleted in batches of 10. Supplying identifiers to the input which exceed this limit will return a LimitExceededError.

A BatchOperationResult type is returned from this method call which contains the status of the batch delete operation. Three possible statuses can be returned:

Status	Definition
Success	All of the draft email messages succeeded to delete.
Partial	Only a subset of draft email messages succeeded to delete. The return object will include a list of identifiers of draft messages which failed the delete and a list which succeeded the delete.
Failure	All of the draft email messages failed to delete.

TypeScript

// Obtain the input draft message ids and email address id however makes sense for your implementation.
val ids = arrayOf('draft-msg-id-1', 'draft-msg-id-2')
val emailAddressId = emailAddress.id
try {
    val deleteResult = await emailClient.deleteDraftEmailMessages({
        ids,
        emailAddressId,
    })
    // `deleteResult` contains the status of the batch delete operation.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input draft message ids and email address id however makes sense for your implementation.
let ids = ['draft-msg-id-1', 'draft-msg-id-2']
let emailAddressId = emailAddress.id
let input = DeleteDraftEmailMessagesInput(
    ids: ids,
    emailAddressId: emailAddressId
)
do {
    let result = try await self.emailClient.deleteDraftEmailMessages(
        withInput: input
    )
    switch result {
    case .success:
        // All draft email messages were deleted successfully
    case. partial:
        // `result.successItems` contains an array of all the draft email
        // message IDs that were deleted successfully.
        // `result.failureItems` cotains an array of all the draft email
        // message IDs that failed to be deleted successfully.
    case .failure:
        // All email messages failed to be deleted.
    }
} catch {
    /// Handle/notify user of error
}

Kotlin

// Obtain the input draft message ids and email address id however makes sense for your implementation.
val ids = listOf("draft-msg-id-1", "draft-msg-id-2")
val emailAddressId = emailAddress.id
launch {
    try {
        val input = DeleteDraftEmailMessagesInput(
            ids = ids,
            emailAddressId = emailAddressId
        )
        val result = withContext(Dispatchers.IO) {
            emailClient.deleteDraftEmailMessages(input)
        }
        when (result) {
            is BatchOperationResult.SuccessOrFailureResult -> {
                // [result.status] contains the status of the batch delete operation.
            }
            is BatchOperationResult.Partial -> {
                // [result.successValues] contains the list of items in which the delete operation succeeded.
                // [result.failureValues] contains the list of items in which the delete operation failed.
            }
        }
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

Retrieving Draft Email Messages

Draft email messages can be accessed using its identifier or by querying for a list of its identifiers.

If a draft email message has been deleted, it will no longer be available for access.

Single Draft Email Message by Id

To retrieve a single draft email message, use the getDraftEmailMessage method. This method takes in the id of the draft to retrieve as well as the id of the email address that is associated with the draft. This method returns the draft email message data if it exists.

TypeScript

// Obtain the input email address id and draft id however makes sense for
// your implementation.
const emailAddressId = emailAddress.id
try {
    const draftMessage = await emailClient.getDraftEmailMessage({
        id,
        emailAddressId,
    })
    // `draftMessage` containing draft message data and `updatedAt` timestamp
    // will be returned if a draft message corresponding to `id` is found,
    // else `undefined`.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input draft message id and email address id however makes sense for your implementation.
let id = 'draft-msg-id-1'
let emailAddressId = emailAddress.id
let input = GetDraftEmailMessageInput(
    id: id,
    emailAddressId: emailAddressId
)
do {
    let draftEmailMessage = try await emailClient.getDraftEmailMessage(
        withInput: input
    )
    // `draftMessage` containing draft message data and `updatedAt` timestamp
    // will be returned if a draft message corresponding to `id` is found,
    // else `nil`.
} catch {
    // Handle/notify user of errors
}

Kotlin

// Obtain the input draft message id and email address id however makes sense for your implementation.
val id = "draft-msg-id-1"
val emailAddressId = emailAddress.id
launch {
    try {
        val input = GetDraftEmailMessageInput(
            id = id,
            emailAddressId = emailAddressId
        )
        val draftMessage = withContext(Dispatchers.IO) {
            emailClient.getDraftEmailMessage(input)
        }
        // [draftMessage] containing draft message data and [updatedAt] timestamp
        // will be returned if a draft message corresponding to [id] is found,
        // else will throw an exception.
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}

List of Draft Email Message Metadata

Use listDraftEmailMessageMetadata to retrieve a list of all the metadata of the draft email messages associated with an email address. The metadata returned in the list can be used to retrieve individual draft email message content, perform an update to an already saved draft, or identify which drafts to perform full retrieval of based on updatedAt timestamp.

TypeScript

// Obtain the input email address id however makes sense for your implementation.
const emailAddressId = emailAddress.id
try {
    const draftMetadata = await emailClient.listDraftEmailMessageMetadata(
        emailAddressId
    )
    // `draftMetadata` is a list of all of the draft email messages'
    // metadata.
} catch (e) {
    // Handle/notify user of errors
}

Swift

// Obtain the input email address id however makes sense for your implementation.
let emailAddressId = emailAddress.id
try {
    let drafts = try await emailClient.listDraftEmailMessageMetadata(
        emailAddressId
    )
    // `drafts` is a an array of `DraftEmailMessageMetadata` of all of the
    // draft email messages' metadata.
} 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 drafts = withContext(Dispatchers.IO) {
            emailClient.listDraftEmailMessageMetadata(emailAddressId)
        }
        // [drafts] is a an array of [DraftEmailMessageMetadata] of all of the
        // draft email messages' metadata.
    } catch (e: EmailMessageException) {
        // Handle/notify user of exception
    }
}