GET/users/{userId}/mail/search

메일을 검색한다.

참고

  • from, to, query 파라미터는 각각 AND 조건으로 검색한다.
  • from/to 기간을 모두 입력하지 않으면 기본값(최근 1년)으로 검색한다.
  • 검색 결과 강조 표시(highlight)를 사용할 수 있다.
    • HTML의 <mark> 태그 지원
    • 예시) 검색어가 "hello" 일 때, 제목, 본문, 파일명에서 일치하는 부분에 대한 처리 : <mark>hello</mark>

Authorization

oauth2

OAuth 2.0 인증.
자세한 인증 방식은 인가·인증를 참고한다.

Scope

mail
mail.read

HTTP Request

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

Path Parameters

ParameterTypeDescription
userId string 

구성원 ID (URL인코딩하여 사용)

  • User ID
  • Login 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 

다음 목록 조회 시 사용하는 값


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: 기밀
  • Non-business: 업무외
 
useForwarding boolean 

메일 재전송 가능 여부

  • true: 가능
  • false: 불가능
 
attachList array (AttachList) 

첨부 파일 정보

 

from

PropertyTypeDescription
name string 

메일 이름

 
email string 

메일 주소 (RFC822 format)


required
minLength : 1 

replyTo

PropertyTypeDescription
name string 

메일 이름

 
email string 

메일 주소 (RFC822 format)


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