GET/users/{userId}/mail/search

メールを検索する。

参考

  • from, to, query パラメータはそれぞれ AND 条件で検索する。
  • from/to の期間を両方とも入力しない場合は、デフォルト値（直近1年）で検索する。
  • 検索結果のハイライト表示（highlight）を使用できる。
    • HTML の <mark> タグをサポート
    • 例）検索語が "hello" の場合、件名・本文・ファイル名で一致する部分に対する処理: <mark>hello</mark>

Authorization

oauth2

Access Token を指定します。
指定の方法や Access Token の取得方法は 共通仕様 を参照してください。

Scope

mail
mail.read

HTTP Request

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

Path Parameters

ParameterTypeDescription
userId string 

ユーザーを特定する ID (URL エンコードする)

  • ユーザー ID (userId)
  • ログイン ID (email)
  • 自身 ("me")

required
example : me 

Query Parameters

ParameterTypeDescription
folderId integer 

検索対象とするメールフォルダ ID
-1 (既定) では、すべてのメールフォルダを対象とする


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

送信者の名前またはメールアドレス

 
to string 

宛先の名前またはメールアドレス

 
query string 

検索語


required 
startTime string 

開始日時（ISO-8601形式、YYYY-MM-DDThh:mm:ssTZD）


format : date-time 
endTime string 

終了日時（ISO-8601形式、YYYY-MM-DDThh:mm:ssTZD）


format : date-time 
previewMode string 

検索結果のプレビュー項目

  • body : メール本文、添付ファイル情報
  • attachment : 添付ファイル情報

default : body
Allowed values : body, attachment 
cursor string 

リストのカーソル値 (URL エンコードする)


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 
count integer 

取得数


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) 

レスポンスメタデータ

 
mails array (object) 
 

responseMetaData

PropertyTypeDescription
nextCursor string 

次の一覧を照会する際に使用するカーソル値

 

object

PropertyTypeDescription
mailId integer 

メール ID

 
folderId integer 

メールフォルダ ID

 
status string 

メールの状態

  • Unread: 未読メール
  • Read: 既読メール
 
from object (from) 

メールアドレス

 
replyTo object (replyTo) 

メールアドレス

 
subject string 

メール件名

 
body string 

メール本文

 
receivedTime string 

メール受信時刻

 
sentTime string 

メール送信時刻

 
size integer 

メールサイズ

 
securityLevel string 

情報レベル

  • General: 公開
  • Restricted: 社外秘
  • Confidential: 機密
 
useForwarding boolean 

再送可否フラグ

  • true: 可能
  • false: 不可能
 
attachList array (AttachList) 

添付ファイル情報

 

from

PropertyTypeDescription
name string 

名前

 
email string 

メールアドレス (RFC822 フォーマット)


required
minLength : 1 

replyTo

PropertyTypeDescription
name string 

名前

 
email string 

メールアドレス (RFC822 フォーマット)


required
minLength : 1 

AttachList

PropertyTypeDescription
attachmentId integer 

添付ファイルID


format : int64 
filename string 

ファイル名

 
fileBody string 

検索語に含まれるファイル内容の一部

 

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": "メール件名",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": "メール件名",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