GET/users/{userId}/mail/search

Searches messages.

Note

  • The from, to, and query parameters are combined with the AND operator for searching.
  • If neither the from nor to parameter is specified, the default search range is the last 1 year.
  • You can highlight search results.
    • Supports the HTML <mark> tag
    • Example) When the search term is "hello", matching parts in the title, body, and file name are processed as: <mark>hello</mark>

Authorization

oauth2

OAuth 2.0 authentication.
For more information, see Authentication and Authorization.

Scope

mail
mail.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/users/{userId}/mail/search

Path Parameters

ParameterTypeDescription
userId string 

Member ID (must be URL-encoded)

  • User ID
  • Login ID (email)
  • Me

required
example : me 

Query Parameters

ParameterTypeDescription
folderId integer 

Folder ID to search. “-1” indicates All mailbox.


default : -1
example : 0
format : int32 
from string 

Sender’s name or email address (partial match)

 
to string 

Sender’s name or email address (partial match)

 
query string 

Search term


required 
startTime string 

Start time (ISO-8601 format, YYYY-MM-DDThh:mm:ssTZD)


format : date-time 
endTime string 

End time (ISO-8601 format, YYYY-MM-DDThh:mm:ssTZD)


format : date-time 
previewMode string 

Search result preview items

  • body: Body and attachment information
  • attachment: Attachment information

default : body
Allowed values : body, attachment 
cursor string 

Cursor value for pagination


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 
count integer 

Number of pages


default : 100
minimum : 1
maximum : 500
format : int32 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Request Body

Response

HTTP 200

OK

PropertyTypeDescription
responseMetaData object (responseMetaData) 

Response metadata

 
mails array (object) 
 

responseMetaData

PropertyTypeDescription
nextCursor string 

Cursor value for pagination

 

object

PropertyTypeDescription
mailId integer 

Message ID

 
folderId integer 

Folder ID

 
status string 

Message status

  • Unread: Unread message
  • Read: Read message
 
from object (from) 

Email information

 
replyTo object (replyTo) 

Email information

 
subject string 

Subject

 
body string 

Body

 
receivedTime string 

Received time

 
sentTime string 

Sent time

 
size integer 

Message size

 
securityLevel string 

Security level of the message

  • General: General
  • Restricted: Restricted
  • Confidential: Confidential
  • Non-business: Non-business
 
useForwarding boolean 

Indicates whether to allow forwarding.

  • true: Allow
  • false: Not allow
 
attachList array (AttachList) 

Attachment information

 

from

PropertyTypeDescription
name string 

Email name

 
email string 

Email address (RFC822 format)


required
minLength : 1 

replyTo

PropertyTypeDescription
name string 

Email name

 
email string 

Email address (RFC822 format)


required
minLength : 1 

AttachList

PropertyTypeDescription
attachmentId integer 

Attachment ID


format : int64 
filename string 

File name

 
fileBody string 

Part of the file contents containing the search term

 

Response Example

Example 1

1{2  "responseMetaData": {3    "nextCursor": "eyJvZmZzZXQiOiIyNDQ3OTAiLCJmaXJzdExvY2F0ZWRBdE9mZnNldCI6IjE3NTMzMDk2MzIuMjY1NDEifQ=="4  },5  "mails": [6    {7      "mailId": 926542,8      "folderId": 6,9      "status": "Unread",10      "from": {11        "name": "admin",12        "email": "admin@example.com"13      },14      "replyTo": {15        "name": "",16        "email": "admin@example.com"17      },18      "subject": "Subject",19      "query": "",20      "receivedTime": "2025-07-24T07:28:05+09:00",21      "sentTime": "2025-07-24T07:28:05+09:00",22      "size": 6282,23      "securityLevel": "General",24      "useForwarding": true25    },26    {27      "mailId": 926541,28      "folderId": 6,29      "status": "Read",30      "from": {31        "name": "admin",32        "email": "admin@example.com"33      },34      "replyTo": {35        "name": "",36        "email": "admin@example.com"37      },38      "subject": "Subject",39      "query": "",40      "receivedTime": "2025-07-24T07:27:12+09:00",41      "sentTime": "2025-07-24T07:27:12+09:00",42      "size": 6285,43      "securityLevel": "General",44      "useForwarding": true45    }46  ]47}

HTTP 400

Bad Request

HTTP 500

Internal Server Error