Sample code for 30+ languages & platforms
Tcl Requires Chilkat v11.0.0+

Move IMAP Messages with OAuth2 and the MOVE Extension

See more IMAP Examples

Move matching messages between two existing mailboxes using QueryMbx and MoveMessages. Gmail OAuth2 supplies the concrete connection example. Other servers require their own authentication settings.

This changes all matching messages in the source folder. Choose the source, destination, and search criterion before running it. Gmail custom folders represent labels; moving between them changes label membership. The code checks MOVE at runtime, handles an empty search, and uses UID-based message sets. It does not fall back to copy/delete/EXPUNGE or print authentication logs. Confirm the result before retrying after a lost connection.

First authorize the mailbox for https://mail.google.com/ and refresh the token as needed. Read the current token from gmail-mail-token.json in a private working directory. Narrow Gmail REST scopes do not authorize these protocols. Keep the token and authentication logs private.

See the Gmail SMTP, IMAP, and POP3 guide for current authentication choices and Gmail-specific examples.

Reference documentation

Chilkat Tcl Downloads

Tcl

load ./chilkat.dll

set success 0

#  Assumes Chilkat is unlocked. See Global Unlock Sample.

set token [new_CkJsonObject]

set success [CkJsonObject_LoadFile $token "gmail-mail-token.json"]
if {$success != 1} then {
    puts "Could not read gmail-mail-token.json from the private working directory."
    delete_CkJsonObject $token
    exit
}

if {expr [[CkJsonObject_JsonTypeOf $token "access_token"] != 1]  ||  [[CkJsonObject_StringOfEquals $token "access_token" "" 1] == 1]} then {
    puts "An OAuth access token is required. Authorize or refresh the account first."
    delete_CkJsonObject $token
    exit
}

set mailbox "user@example.com"
set imap [new_CkImap]

CkImap_put_Ssl $imap 1
CkImap_put_Port $imap 993
CkImap_put_RequireSslCertVerify $imap 1
CkImap_put_AuthMethod $imap "XOAUTH2"
set success [CkImap_Connect $imap "imap.gmail.com"]
if {$success != 1} then {
    puts "Could not establish the Gmail IMAP TLS connection."
    delete_CkJsonObject $token
    delete_CkImap $imap
    exit
}

set success [CkImap_Login $imap $mailbox [CkJsonObject_stringOf $token "access_token"]]
if {$success != 1} then {
    CkImap_Disconnect $imap
    puts "IMAP authentication failed. Check the mailbox, token scope, expiry, and Workspace policy."
    delete_CkJsonObject $token
    delete_CkImap $imap
    exit
}

set capabilities [CkImap_capability $imap]
if {expr [[CkImap_get_LastMethodSuccess $imap] != 1]  ||  [[CkImap_HasCapability $imap "MOVE" $capabilities] != 1]} then {
    CkImap_Logout $imap
    CkImap_Disconnect $imap
    puts "This example requires the MOVE capability."
    delete_CkJsonObject $token
    delete_CkImap $imap
    exit
}

#  These existing custom-label folders are inputs. The operation moves matching messages.
set sourceFolder "Example"
set destinationFolder "Example/Processed"
set success [CkImap_SelectMailbox $imap $sourceFolder]
if {$success != 1} then {
    CkImap_Logout $imap
    CkImap_Disconnect $imap
    puts "Could not select the source folder."
    delete_CkJsonObject $token
    delete_CkImap $imap
    exit
}

set selected [new_CkMessageSet]

set success [CkImap_QueryMbx $imap "FROM sender@example.net" 1 $selected]
if {$success != 1} then {
    CkImap_Logout $imap
    CkImap_Disconnect $imap
    puts "Could not search the source folder."
    delete_CkJsonObject $token
    delete_CkImap $imap
    delete_CkMessageSet $selected
    exit
}

if {[CkMessageSet_get_Count $selected] == 0} then {
    CkImap_Logout $imap
    CkImap_Disconnect $imap
    puts "No matching messages; nothing was moved."
    delete_CkJsonObject $token
    delete_CkImap $imap
    delete_CkMessageSet $selected
    exit
}

puts "Moving UID set: [CkMessageSet_toCompactString $selected]"
set success [CkImap_MoveMessages $imap $selected $destinationFolder]
if {$success != 1} then {
    CkImap_Logout $imap
    CkImap_Disconnect $imap
    puts "Move failed. Verify the outcome before retrying an interrupted operation."
    delete_CkJsonObject $token
    delete_CkImap $imap
    delete_CkMessageSet $selected
    exit
}

puts "MOVE completed for the selected messages."
CkImap_Logout $imap
CkImap_Disconnect $imap

delete_CkJsonObject $token
delete_CkImap $imap
delete_CkMessageSet $selected