Outlook Mail: Filter or Search Messages in a Folder
See more Outlook Examples
Choose either an exact OData filter (unread messages from an address) or a quoted text-search expression such as "subject:sample" or "body:sample". OData string-literal escaping and URL encoding are separate steps. Validate/escape application input for the query language you use; URL encoding alone does not prevent changing the query expression.
Message $search is indexed text search, not an arbitrary substring scan, and returns at most 1000 results ordered by sent time. Pagination does not remove that cap. Use narrower searches, filtered enumeration, or synchronization for exhaustive processing. This example does not combine $search with $filter/$orderby. When combining $filter with $orderby in other code, Graph imposes property-order rules to avoid InefficientFilter. The old body/content contains filter is replaced with documented body text search.
Follows the complete @odata.nextLink, including empty pages with a continuation. The example checks the Graph host, rejects repeated links, and stops explicitly after 100 pages; this is a demonstration bound, not an API limit. Save the next URL privately to resume larger scans. $top controls page size, not the total result count.
IDs are opaque, case-sensitive strings, not numbers or Internet Message-ID headers. URL-encode each ID as a path segment. Message examples request Prefer: IdType="ImmutableId" consistently so moves within the same mailbox retain the ID. Retrieve IDs with that preference or deliberately convert older IDs; do not change their characters or assume an old default-format ID is immutable.
Delegated permission: Mail.Read.
Uses direct Chilkat.Http calls to Microsoft Graph v1.0 for an Outlook.com or Microsoft 365 online mailbox. Save a current Graph access token as access_token in the private file qa_data/tokens/microsoftGraph.json. Obtain it through the Microsoft identity platform authorization-code flow with PKCE for a public interactive client; request offline_access if a refresh token is needed. Consent to the mail permission stated here. Tokens for SMTP/IMAP/POP, Calendar-only, or Contacts-only access are insufficient.
/me requires a signed-in user and delegated permissions. An unattended Microsoft 365 application instead uses administrator-approved application permissions and /users/{id-or-UPN}; limit it to the intended mailboxes. Client credentials is not available for personal Outlook.com mailboxes. These requests access cloud mailbox data, not local PST files, and do not require Outlook to be running. National clouds require their own authority and Graph hosts.
The code checks the HTTP status separately from transport success and validates JSON before reading it. For 401, refresh or authorize again; for 403, check consent, mailbox access, and policy; for 429, honor Retry-After with a bounded retry. A failed or timed-out write can have an uncertain outcome: reconcile before repeating it. Keep tokens, message content, continuation URLs, and detailed diagnostics private.
Chilkat Delphi DLL Downloads
var
success: Boolean;
replaceCount: Integer;
token: HCkJsonObject;
http: HCkHttp;
resp: HCkHttpResponse;
result: HCkJsonObject;
useTextSearch: Boolean;
senderAddress: PWideChar;
filter: HCkStringBuilder;
escapedSender: PWideChar;
searchExpression: PWideChar;
folderId: PWideChar;
endpoint: HCkStringBuilder;
url: PWideChar;
nextLink: HCkStringBuilder;
seenLinks: HCkStringArray;
pageCount: Integer;
i: Integer;
nextType: Integer;
begin
success := False;
// Assumes Chilkat is unlocked. See Global Unlock Sample.
success := False;
replaceCount := 0;
// Supply a current Microsoft Graph token with this example's mail permissions.
// Keep the token cache private and refresh expired tokens before running the example.
token := CkJsonObject_Create();
CkJsonObject_putStrict(token,True);
success := CkJsonObject_LoadFile(token,'qa_data/tokens/microsoftGraph.json');
if (success <> True) then
begin
Memo1.Lines.Add('Could not read the private Graph token cache.');
Exit;
end;
if ((CkJsonObject_JsonTypeOf(token,'access_token') <> 1) or (CkJsonObject_StringOfEquals(token,'access_token','',True) = True)) then
begin
Memo1.Lines.Add('Expected a nonempty access_token in the JSON.');
Exit;
end;
http := CkHttp_Create();
CkHttp_putAuthToken(http,CkJsonObject__stringOf(token,'access_token'));
CkHttp_putRequireSslCertVerify(http,True);
CkHttp_putFollowRedirects(http,False);
CkHttp_putConnectTimeout(http,20);
CkHttp_putReadTimeout(http,60);
CkHttp_SetRequestHeader(http,'Accept','application/json');
resp := CkHttpResponse_Create();
result := CkJsonObject_Create();
CkJsonObject_putStrict(result,True);
CkHttp_SetRequestHeader(http,'Prefer','IdType="ImmutableId"');
// Choose one query mode; do not combine $filter and $search here.
useTextSearch := False;
senderAddress := 'sender@example.com';
filter := CkStringBuilder_Create();
CkStringBuilder_Append(filter,senderAddress);
// Escape OData string-literal quotes BEFORE URL encoding the whole expression.
replaceCount := CkStringBuilder_Replace(filter,'''','''''');
escapedSender := CkStringBuilder__getAsString(filter);
CkStringBuilder_SetString(filter,'isRead eq false and from/emailAddress/address eq ''');
CkStringBuilder_Append(filter,escapedSender);
CkStringBuilder_Append(filter,'''');
// Alternatives: isRead eq false, or receivedDateTime ge 2026-01-01T00:00:00Z.
// Text search uses quoted KQL; this is a trusted expression, not unescaped user input.
searchExpression := '"subject:sample"';
folderId := 'inbox';
endpoint := CkStringBuilder_Create();
CkStringBuilder_Append(endpoint,'https://graph.microsoft.com/v1.0/me/mailFolders/');
CkStringBuilder_Append(endpoint,CkHttp__urlEncode(http,folderId));
CkStringBuilder_Append(endpoint,'/messages');
if (useTextSearch = True) then
begin
CkStringBuilder_Append(endpoint,'?$search=');
CkStringBuilder_Append(endpoint,CkHttp__urlEncode(http,searchExpression));
end
else
begin
CkStringBuilder_Append(endpoint,'?$filter=');
CkStringBuilder_Append(endpoint,CkHttp__urlEncode(http,CkStringBuilder__getAsString(filter)));
end;
CkStringBuilder_Append(endpoint,'&$select=id,subject,from&$top=50');
url := CkStringBuilder__getAsString(endpoint);
nextLink := CkStringBuilder_Create();
seenLinks := CkStringArray_Create();
pageCount := 0;
while ((url <> '') and (pageCount < 100)) do
begin
CkStringBuilder_SetString(nextLink,url);
if (CkStringBuilder_StartsWith(nextLink,'https://graph.microsoft.com/v1.0/',True) <> True) then
begin
Memo1.Lines.Add('Unexpected pagination host or API version; no request sent.');
Exit;
end;
if (CkStringArray_Find(seenLinks,url,0) >= 0) then
begin
Memo1.Lines.Add('Repeated pagination URL; stopping.');
Exit;
end;
CkStringArray_Append(seenLinks,url);
success := CkHttp_HttpNoBody(http,'GET',url,resp);
// A false result can still include an HTTP error response.
if ((success <> True) and (CkHttpResponse_getStatusCode(resp) = 0)) then
begin
Memo1.Lines.Add('No HTTP response was received. Inspect diagnostics privately; reconcile a write before retrying.');
Exit;
end;
if (CkHttpResponse_getStatusCode(resp) <> 200) then
begin
Memo1.Lines.Add('Unexpected HTTP status: ' + IntToStr(CkHttpResponse_getStatusCode(resp)));
Memo1.Lines.Add('Request ID: ' + CkHttpResponse__getHeaderField(resp,'request-id'));
if (CkHttpResponse_getStatusCode(resp) = 429) then
begin
Memo1.Lines.Add('Retry-After: ' + CkHttpResponse__getHeaderField(resp,'Retry-After'));
end;
if (CkHttpResponse_getStatusCode(resp) = 401) then
begin
Memo1.Lines.Add('Refresh the Graph access token or authorize again.');
end;
Exit;
end;
success := CkJsonObject_Load(result,CkHttpResponse__bodyStr(resp));
if (success <> True) then
begin
Memo1.Lines.Add('Expected a well-formed JSON response.');
Exit;
end;
if (CkJsonObject_JsonTypeOf(result,'value') <> 4) then
begin
Memo1.Lines.Add('Expected a value array.');
Exit;
end;
i := 0;
while (i < CkJsonObject_SizeOfArray(result,'value')) do
begin
CkJsonObject_putI(result,i);
if ((CkJsonObject_JsonTypeOf(result,'value[i].id') <> 1) or (CkJsonObject_StringOfEquals(result,'value[i].id','',True) = True)) then
begin
Memo1.Lines.Add('Expected a nonempty value[i].id in the JSON.');
Exit;
end;
Memo1.Lines.Add('Message ID: ' + CkJsonObject__stringOf(result,'value[i].id'));
Memo1.Lines.Add('Subject: ' + CkJsonObject__stringOf(result,'value[i].subject'));
Memo1.Lines.Add('From: ' + CkJsonObject__stringOf(result,'value[i].from.emailAddress.address'));
i := i + 1;
end;
pageCount := pageCount + 1;
// A quoted JSON path treats the period in @odata.nextLink literally.
nextType := CkJsonObject_JsonTypeOf(result,'"@odata.nextLink"');
if ((nextType = -1) or (nextType = 6)) then
begin
url := '';
end
else
begin
if ((nextType <> 1) or (CkJsonObject_StringOfEquals(result,'"@odata.nextLink"','',True) = True)) then
begin
Memo1.Lines.Add('Invalid continuation link; cannot establish completeness.');
Exit;
end;
url := CkJsonObject__stringOf(result,'"@odata.nextLink"');
end;
end;
if (url <> '') then
begin
Memo1.Lines.Add('Stopped at the example''s 100-page limit; save the continuation privately to resume.');
Exit;
end;
Memo1.Lines.Add('Completed pages: ' + IntToStr(pageCount));
CkJsonObject_Dispose(token);
CkHttp_Dispose(http);
CkHttpResponse_Dispose(resp);
CkJsonObject_Dispose(result);
CkStringBuilder_Dispose(filter);
CkStringBuilder_Dispose(endpoint);
CkStringBuilder_Dispose(nextLink);
CkStringArray_Dispose(seenLinks);