Objective-C

Search an IMAP Mailbox

Demonstrates the Chilkat Imap.QueryMbx method, which searches the selected mailbox using IMAP search criteria and stores the matching message identifiers in a MessageSet. If bUid is true, the identifiers are UIDs; otherwise they are sequence numbers. This example finds unseen messages and lists their UIDs.

Background: IMAP search runs on the server, so you can find matching messages without downloading them. The criteria string is standard IMAP search syntax — for example UNSEEN, FROM "alice@example.com", SUBJECT "invoice", or SINCE 1-Jan-2026 — and terms can be combined. The result is a MessageSet of identifiers you then fetch, flag, copy, or move. Requesting UIDs (bUid = true) is preferred because UIDs remain valid across sessions.

Chilkat Objective-C Downloads

Download Chilkat for Objective-C

Objective-C

#import <CkoImap.h>
#import <CkoMessageSet.h>

BOOL success = NO;

//  Demonstrates the Imap.QueryMbx method, which searches the selected mailbox using IMAP
//  search criteria and stores the matching message identifiers in a MessageSet.  If bUid is
//  true, the identifiers are UIDs; otherwise they are sequence numbers.

CkoImap *imap = [[CkoImap alloc] init];

imap.Ssl = YES;
imap.Port = [NSNumber numberWithInt:993];

success = [imap Connect: @"imap.example.com"];
if (success == NO) {
    NSLog(@"%@",imap.LastErrorText);
    return;
}

success = [imap Login: @"user@example.com" password: @"myPassword"];
if (success == NO) {
    NSLog(@"%@",imap.LastErrorText);
    return;
}

success = [imap SelectMailbox: @"Inbox"];
if (success == NO) {
    NSLog(@"%@",imap.LastErrorText);
    return;
}

//  Search for unseen (unread) messages, returning their UIDs.
CkoMessageSet *msgSet = [[CkoMessageSet alloc] init];
success = [imap QueryMbx: @"UNSEEN" bUid: YES msgSet: msgSet];
if (success == NO) {
    NSLog(@"%@",imap.LastErrorText);
    return;
}

//  Iterate the matching message identifiers.
int n = [msgSet.Count intValue];
NSLog(@"%@%d",@"Matching messages: ",n);
int i;
for (i = 0; i <= n - 1; i++) {
    NSLog(@"%@%d",@"UID: ",[msgSet GetId: [NSNumber numberWithInt: i]]);
}

success = [imap Disconnect];
if (success == NO) {
    NSLog(@"%@",imap.LastErrorText);
    return;
}