메일

메일 연계 API 이용을 위한 상세 개발 가이드입니다.
메일 API는 메일 발신, 발신 취소, 상태 조회 세 가지 유형으로 나누어져 있습니다.

[정책 및 제약사항]

1. 발신인 정보는 녹스포탈 임직원만 지정 가능하며, 발신자의 거점으로 연계 호출해야 합니다.
2. 본문 사이즈는 최대 1MB 를 넘을 수 없습니다.
3. 한번에 10개의 첨부파일을 포함하여 발송할 수 있으며, 전체 첨부 사이즈는 10MB 를 넘을 수 없습니다.
4. 수신인은 최대 200명까지 지정이 가능합니다.

[API 목록] 테스트 페이지로 이동(Swagger)_{*Chrome Browser만 이용 가능합니다.}

API	URI	Method	Description

일반 메일 발신	/mail/api/v2.0/mails/send?userId=Knox아이디	POST	Knox 메일을 발신한다.
대외비 메일 발신	/mail/api/v2.0/mails/secu-send?userId=Knox아이디	POST	Knox 대외비 메일을 발신한다.
메일 발신 취소	/mail/api/v2.0/mails/{mailId}/cancel?userId=Knox아이디	POST	Knox 내부로 발신한 메일을 발신 취소한다.
메일 별 수신상태 조회	/mail/api/v2.0/mails/deliverystatus/count?userId=Knox아이디	POST	해당하는 메일에 대해서 전체 수신 상태를 조회한다.
수신인 별 수신상태 조회	/mail/api/v2.0/mails/{mailId}/deliverystatus?userId=Knox아이디	GET	해당하는 메일에 대해서 수신인 별 수신 상태를 조회한다.

일반 메일 발신

/mail/api/v2.0/mails/send?userId=Knox아이디

삼성 그룹사 임직원 뿐만 아니라 외부수신인을 포함하여 메일 발신이 가능하며, 발신된 메일을 발신함에 저장됩니다.

주 1. 발신자의 메일>환경설정> 발신메일저장옵션에 따라 다를 수 있습니다.

주 2. Multipart/form-data 구성시 아래 Sample Request 와 같이 각 파트를 구분하여 form-data 의 name 값을 ‘mail’ , ‘attachments’ 로 호출해야 합니다.

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 시스템 아이디	System-ID	Y	Header	String	C60LD0001
2	유저 아이디	userId	Y	Query	String	knoxportal
3	메일 제목	subject	Y	Body	String	메일 제목입니다.
4	문서 타입	docSecuType	Y	Body	String	PERSONAL	1) PERSONAL : 개인 2) OFFICIAL : 공문
5	메일 본문	contents	Y	Body	String	안녕하세요, 테스트 메일입니다.
6	컨텐츠 타입	contentType	Y	Body	String	TEXT	1) TEXT : 텍스트 2) MIME : 마임 3) HTML : HTML
7	발신인	sender	Y	Body	JSON Object
8	발신인 이메일	emailAddress	Y	Body	String	knoxportal@samsung.com	1) 운영 환경 : knoxportal@samsung.com 2) 스테이지 환경 : knoxportal@stage.samsung.com
9	수신인	recipients	Y	Body	JSON List
10	수신인 이메일	emailAddress	Y	Body	String	knoxportal@samsung.com	1) 운영 환경 : knoxportal@samsung.com 2) 스테이지 환경 : knoxportal@stage.samsung.com
11	수신 타입	recipientType	Y	Body	String	TO	1) 수신 : TO 2) 참조 : CC 3) 비밀참조 : BCC
12	첨부 파일	attachments	N	Body	multipart/form-data	multipart/form-data로 변환된 바이너리 파일 및 파일명
13	예약 발신	reservedTime	N	Body	String	yyyy-MM-dd HH:mm ex)"2023-10-25 15:00"	10분 단위 설정

Response Parameter

Properties	Attribute	Data Type	Sample Data	Note

API 호출 성공 여부	result	String	success
메일 아이디	mailId	String	20190409043651epcms1s110a09b3ca1b6c8d754ee1c28a182d8d5

Sample

Request	Response

/mail/api/v2.0/mails/send?userId=knoxportal
body :

Content-Disposition: form-data; name="mail"
{
   "subject" : "EMAIL SUBJECT (이메일 제목)",
   "contents" : "EMAIL BODY (이메일 본문)",
   "contentType" : "TEXT",
   "docSecuType" : "PERSONAL",
   "sender" :
      {
         "emailAddress" : "knoxportal@samsung.com"
      },
   "recipients" :
      [
         {
            "emailAddress" : "knoxportal@samsung.com",
            "recipientType" : "TO"
         }
      ]
}
Content-Disposition: form-data; name="attachments"; filename="db변경.JPG"
Content-Type: image/jpeg
Content-Disposition: form-data; name="attachments"; filename="2 - 복사본 (2).jpg"
Content-Type: image/jpeg

{
"mailId": "20190531015540hdp_101d2782e07bbad98034606076da1e299b05",
"result": "success"
}

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ML1001	필수값 중 입력되지 않은 값이 있습니다.	모든 필수값이 입력되었는지 확인이 필요합니다. 또, 에러 메시지에 null인 parameter 명이 리턴된다면, 해당 값을 우선적으로 확인해야 합니다.
400	ML1002	사용자 정보가 존재하지 않습니다.	호출 시 입력하는 URI 상의 Knox Id, 혹은 메일 발신자 knox 이메일 addresss가 정상적인지 확인이 필요합니다.
400	ML1104	일반 메일 발신 중 docSecuType 값이 유효하지 않습니다.	일반 메일의 docSecuType은 PERSONAL(개인), OFFICIAL(공문) 두 값만 허용됩니다.
400	ML1112	메일 제목 크기가 300 bytes를 초과하였습니다.	제목의 사이즈 확인이 필요합니다.
400	ML1114	메일 발신 API에서 허용되는 content 크기를 초과하였습니다.	발신 API에서 본문 사이즈는 최대 1mb까지 입력이 가능합니다. 해당 크기를 초과하는 내용에 대해서는 가급적 첨부 파일 등을 이용 부탁드립니다.
400	ML1115	일반 메일 contentType 값이 유효하지 않습니다	일반 메일의 contentType 값은 HTML, MIME, TEXT 세 개의 값만 허용됩니다.
400	ML1117	메일 발신 API에서 발신가능한 최대 수신인을 초과하였습니다.	입력 가능한 최대 수신인 수는 100명입니다.
400	ML1118	수신자의 수신 타입이 잘못 설정되었습니다.	수신 타입은 TO(수신), CC(참조), BCC(비밀참조) 세 개의 값만 허용됩니다.
403	ML1102	첨부 파일 처리 중 에러가 발생했습니다.	첨부 파일의 Multipart/form-data 형식 확인이 필요합니다.
400	CO400	잘못된 요청입니다.	요청 파라미터를 확인해주세요. 특히 userId, docSecuType 이 누락되었는지 확인해주세요.

대외비 메일 발신

/mail/api/v2.0/mails/secu-send?userId=Knox아이디

대외비, 극비로 설정하여 보안 메일을 발송할 수 있습니다.
보안 메일 옵션을 설정할 수 있습니다.

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 시스템 아이디	System-ID	Y	Header	String	C60LD0001
2	유저 아이디	userId	Y	Query	String	knoxportal
3	메일 제목	subject	Y	Body	String	메일 제목입니다.
4	문서 타입	docSecuType	Y	Body	String	PERSONAL	1) PERSONAL : 개인 2) OFFICIAL : 공문
5	메일 본문	contents	Y	Body	String	안녕하세요, 테스트 메일입니다.
6	컨텐츠 타입	contentType	Y	Body	String	TEXT	1) TEXT : 텍스트 2) MIME : 마임 3) HTML : HTML
7	발신인	sender	Y	Body	JSON Object
8	발신인 이메일	emailAddress	Y	Body	String	knoxportal@samsung.com	1) 운영 환경 : knoxportal@samsung.com 2) 스테이지 환경 : knoxportal@stage.samsung.com
9	수신인	recipients	Y	Body	JSON List
10	수신인 이메일	emailAddress	Y	Body	String	knoxportal@samsung.com	1) 운영 환경 : knoxportal@samsung.com 2) 스테이지 환경 : knoxportal@stage.samsung.com
11	수신 타입	recipientType	Y	Body	String	TO	1) 수신 : TO 2) 참조 : CC 3) 비밀참조 : BCC
12	첨부 파일	attachments	N	Body	multipart/form-data	multipart/form-data로 변환된 바이너리 파일 및 파일명
13	대외비 옵션	drmOption	Y	JSON Object	String
14	대외비 메일 조회 가능 일 수	validDays	Y	Body	String	3
15	대외비 개봉 가능 횟수	useCount	Y	Body	String	3
16	대외비 수신인 조회 가능 여부	canView	Y	Body	String	0
17	대외비 인쇄 가능 여부	canPrint	Y	Body	String	0
18	대외비 외부 수신인의 개봉 알림 여부	notifyExternalUser	Y	Body	String	0
19	대외비 내부 수신인의 개봉 알림 여부	notifyInternalUser	Y	Body	String	0

Response Parameter

Properties	Attribute	Data Type	Sample Data	Note

API 호출 성공 여부	result	String	success
mailId	메일 아이디	String	20190409043651epcms1s110a09b3ca1b6c8d754ee1c28a182d8d5

Sample

Request	Response

/mail/api/v2.0/mails/send?userId=knoxportal
body :

Content-Disposition: form-data; name="mail"
{
   "subject" : "EMAIL SUBJECT (이메일 제목)",
   "contents" : "EMAIL BODY (이메일 본문)",
   "contentType" : "TEXT",
   "docSecuType" : "PERSONAL",
   "sender" :
      {
         "emailAddress" : "knoxportal@samsung.com"
      },
   "recipients" :
      [
         {
            "emailAddress" : "knoxportal@samsung.com",
            "recipientType" : "TO"
         }
      ],
   "drmOption" :
      {
         "validDays":"3",
         "useCount":"3",
         "canView":"0",
         "canPrint":"0",
         "notifyExternalUser":"0",
         "notifyInternalUser":"0"
      }
}
Content-Disposition: form-data; name="attachments"; filename="db변경.JPG"
Content-Type: image/jpeg
Content-Disposition: form-data; name="attachments"; filename="2 - 복사본 (2).jpg"
Content-Type: image/jpeg

{
"mailId": "20190531015540hdp_101d2782e07bbad98034606076da1e299b05",
"result": "success"
}

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ML1001	필수값 중 입력되지 않은 값이 있습니다.	모든 필수값이 입력되었는지 확인이 필요합니다. 또, 에러 메시지에 null인 parameter 명이 리턴된다면, 해당 값을 우선적으로 확인해야 합니다.
400	ML1002	사용자 정보가 존재하지 않습니다.	호출 시 입력하는 URI 상의 Knox Id, 혹은 메일 발신자 knox 이메일 addresss가 정상적인지 확인이 필요합니다.
400	ML1101	본문 (content) 값이 입력되지 않았습니다.	메일 발신 관련 API에서 본문 (content) 값이 정상적으로 입력되었는지 확인이 필요합니다.
400	ML1107	대외비/극비 보안 옵션 값이 유효하지 않습니다. 옵션 값을 확인해주세요.	대외비/극비의 보안 옵션 설정 유효 값을 가이드를 통해 확인 후 입력이 필요합니다.
400	ML1108	대외비/극비 메일 contentType 값이 유효하지 않습니다.	대외비/극비 메일에서 contentType은 HTML과 TEXT 타입만 허용됩니다.
400	ML1109	대외비/극비 메일 docSecuType 값이 유효하지 않습니다.	대외비/극비 메일의 docSecuType은 CONFIDENTIAL(대외비), CONFIDENTIAL_STRICT(극비) 두 값만 허용됩니다.
400	ML1110	극비 메일일 경우에는 내부 수신인에게만 메일 발신이 가능합니다.	외부 수신인 혹은 유효하지 않은 Knox 이메일 계정이 수신인에 포함되지 않았는지 확인이 필요합니다.
400	ML1111	대외비/극비 메일에서 허용되지 않는 첨부 파일의 확장자가 있습니다.	txt, doc, ppt, xls, pdf, jpg, jpeg, gif, bmp, docx, pptx, xlsx, mht, gul 확장자만 허용됩니다.
400	ML1112	메일 제목 크기가 300 bytes를 초과하였습니다.	제목의 사이즈 확인이 필요합니다.
400	ML1114	메일 발신 API에서 허용되는 content 크기를 초과하였습니다.	발신 API에서 본문 사이즈는 최대 1mb까지 입력이 가능합니다. 해당 크기를 초과하는 내용에 대해서는 가급적 첨부 파일 등을 이용 부탁드립니다.
400	ML1117	메일 발신 API에서 발신가능한 최대 수신인을 초과하였습니다.	입력 가능한 최대 수신인 수는 100명입니다.
400	ML1118	수신자의 수신 타입이 잘못 설정되었습니다.	수신 타입은 TO(수신), CC(참조), BCC(비밀참조) 세 개의 값만 허용됩니다.
403	ML1102	첨부 파일 처리 중 에러가 발생했습니다.	첨부 파일의 Multipart/form-data 형식 확인이 필요합니다.

메일 발신 취소

/mail/api/v2.0/mails/{mailId}/cancel?userId=Knox아이디

Knox 사용자가 발신한 메일을, 수신자의 수신 메일함에서 삭제하는 기능입니다.
(주) Knox 외부로 보낸 메일에 대해서는 발신 취소가 불가능합니다.

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 시스템 아이디	System-ID	Y	Header	String	C60LD0001
2	메일 아이디	{mailId}	Y	Path	String	20190623111845epcms1v2dd0e6bfd951d8f03bd75cd90afacdf8a	발신된 모든 메일은 메일아이디라는 고유값을 가지며, 메일 발신이 성공하면 메일아이디를 전달받습니다. 전달받은 메일아이디를 활용하여 발신취소 또는 수신상황 조회를 할 수 있습니다.
3	유저 아이디	userId	Y	Query	String	knoxportal
4	수신인	recipients	Y	Body	String

Response Parameter

Properties	Attribute	Data Type	Sample Data	Note

API 호출 성공 여부

result

String

success

Sample

Request	Response

/mail/api/v2.0/mails/20190623111845epcms1v2dd0e6bfd951d8f03bd75cd90afacdf8a/cancel?userId=knoxportal
Content-Type : application/json;
body :
{
"recipients" : ["sample.id@samsung.com","knoxportal@samsung.com"]
}

{
"result": "success"
}

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ML1001	필수값 중 입력되지 않은 값이 있습니다.	모든 필수값이 입력되었는지 확인이 필요합니다. 또, 에러 메시지에 null인 parameter 명이 리턴된다면, 해당 값을 우선적으로 확인해야 합니다.
400	ML1002	사용자 정보가 존재하지 않습니다.	호출 시 입력하는 URI 상의 Knox Id, 혹은 메일 발신자 knox 이메일 addresss가 정상적인지 확인이 필요합니다.
404	ML1003	요청하신 데이터가 존재하지 않습니다.	호출 시 입력한 MailId에 해당되는 메일 데이터가 존재하지 않습니다. 발신취소 및 상태조회 하고자 하는 발신자/수신자 정보 확인이 필요합니다.

메일 별 수신상태 조회

/mail/api/v2.0/mails/deliverystatus/count?userId=Knox아이디

전달받은 메일 ID 리스트에 대해서, 각각의 전체적인 수신상태를 조회할 수 있습니다.

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 시스템 아이디	System-ID	Y	Header	String	C60LD0001
2	유저 아이디	userId	Y	Query	String	knoxportal
3	메일 아이디 리스트	mailIds	Y	Body	String	20190623111845epcms1v2dd0e6bfd951d8f03bd75cd90afacdf8a

Response Parameter

Properties	Attribute	Data Type	Sample Data	Note

메일 아이디	mailId	String	20190409043651epcms1s110a09b3ca1b6c8d754ee1c28a182d8d5
전체 카운트	totalStatusCount	int	8
배달중	sendingCount	int	0
개봉	openCount	int	1
미개봉	unopenCount	int	7
기타	etcCount	int	0
발신취소	sendCancelCount	int	0
발신취소 요청중	sendCancelReqCount	int	0
발신차단	sendBlockCount	int	0
발신실패	sendFailCount	int	0
대외비 변환중	drmProcessCount	int	0
대외비 변환 실패	drmFailCount	int	0
예약	reserveCount	int	0
예약 취소	reserveCancelCount	int	0
알수없음	unknownCount	int	0

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ML1001	필수값 중 입력되지 않은 값이 있습니다.	모든 필수값이 입력되었는지 확인이 필요합니다. 또, 에러 메시지에 null인 parameter 명이 리턴된다면, 해당 값을 우선적으로 확인해야 합니다.
400	ML1002	사용자 정보가 존재하지 않습니다.	호출 시 입력하는 URI 상의 Knox Id, 혹은 메일 발신자 knox 이메일 addresss가 정상적인지 확인이 필요합니다.
404	ML1003	요청하신 데이터가 존재하지 않습니다.	호출 시 입력한 MailId에 해당되는 메일 데이터가 존재하지 않습니다. 발신취소 및 상태조회 하고자 하는 발신자/수신자 정보 확인이 필요합니다.

수신인 별 수신상태 조회

/mail/api/v2.0/mails/{mailId}/deliverystatus?userId=Knox아이디

전달받은 메일 ID에 대해서, 해당 메일의 수신인 별 수신 상태를 조회할 수 있습니다.

Request Parameter

No.	Properties	Attribute	Mandatory	Parameter Type	Data Type	Sample Data	Note

1	연계 시스템 아이디	System-ID	Y	Header	String	C60LD0001
2	메일 아이디	{mailId}	Y	Path	String	20190623111845epcms1v2dd0e6bfd951d8f03bd75cd90afacdf8a	발신된 모든 메일은 메일아이디라는 고유값을 가지며, 메일 발신이 성공하면 메일아이디를 전달받습니다. 전달받은 메일아이디를 활용하여 발신취소 또는 수신상황 조회를 할 수 있습니다.
3	유저 아이디	userId	Y	Query	String	knoxportal

Response Parameter

Properties	Attribute	Data Type	Sample Data	Note

이름	name	String	KnoxPortal
직급	position	String	Senior Engineer
영문 성명	enName	String	KnoxPortal ServiceDesk
영문 직급	enPosition	String	Senior Engineer
회사명	company	String	삼성SDS
부서명	department	String	사업그룹(Knox Portal)
영문 부서명	enDepartment	String	Business Group
이메일 주소	email	String	knoxportal@samsung.com
유저 ID	userID	String	knoxportal
수신타입	recipientType	String	TO
수신상태가 업데이트된 시간	updateTime	Calendar	{"month":6,"year":2019,"dayOfMonth":7,"hourOfDay":5,"minute":48,"second":16}
개봉상태	status	String	UNOPEN
수신자가 메일 개봉시 발신자에게 알림 여부	needOpenNotify	boolean	false
DL 메일주소 여부값	isDLAddr	boolean	false

Error Code

HTTP응답코드	에러코드	에러메시지	조치방안

400	ML1001	필수값 중 입력되지 않은 값이 있습니다.	모든 필수값이 입력되었는지 확인이 필요합니다. 또, 에러 메시지에 null인 parameter 명이 리턴된다면, 해당 값을 우선적으로 확인해야 합니다.
400	ML1002	사용자 정보가 존재하지 않습니다.	호출 시 입력하는 URI 상의 Knox Id, 혹은 메일 발신자 knox 이메일 addresss가 정상적인지 확인이 필요합니다.
404	ML1003	요청하신 데이터가 존재하지 않습니다.	호출 시 입력한 MailId에 해당되는 메일 데이터가 존재하지 않습니다. 발신취소 및 상태조회 하고자 하는 발신자/수신자 정보 확인이 필요합니다.