Notification > Email > API v1.1 가이드

[API 도메인]

환경 도메인
리얼 https://api-mail.cloud.toast.com

[Header]

Content-Type: application/json;charset=UTF-8

[curl 예시 주의 사항]

  • Windows cmd에서는 curl 예시가 정상적으로 요청되지 않을 수 있습니다.

메일 발송

일반 메일 발송

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/sender/mail

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Request body]

타입 필수 설명
​senderAddress String O 발신자 메일
senderName String X 발신자 이름
requestDate String X 발송 일자 미입력 시 현재 시간으로 발송(yyyy-MM-dd HH:mm:ss)
title String O 제목
body String O 내용
attachFileIdList List:String X 업로드한 첨부 파일 ID
templateId String X 발송 템플릿 ID
templateParameter Object X 치환 파라미터(메일 제목/내용 치환 시 입력)
- #key# String X 치환 키(##key##)
- #value# Object X 치환 키에 매핑되는 Value값
receiverList List O 수신자 목록
최대 1,000명까지 발송 가능(받는 사람, 참조자 포함)
- receiveMailAddr String O 수신자 메일 주소
- receiveName String X 수신자 이름
- receiveType String O 수신자 유형(MRT0: 받는 사람 , MRT1: 참조, MRT2: 숨은 참조)
customHeaders Map X 사용자 지정 헤더
userId String X 발송 구분자 예) admin, system

[주의]

  • template을 사용할 경우 title, body는 필수입력 제외(입력 시 입력된 값이 template보다 우선 적용)

  • templateParameter 인자를 사용할 때는 templateId 인자를 필수로 입력

[예시 1]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/mail -d '{"senderAddress":"support@nhnent.com","senderName":"발송자이름","title":"샘플 타이틀","body":"샘플 내용","receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1","receiveType":"MRT0"},{"receiveMailAddr":"customer2@nhnent.com","receiveName":"고객2","receiveType":"MRT1"}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

[예시 2 - 템플릿 사용]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/mail -d '{"templateId":"TEMPLATE1","templateParameter":{"key":"value"},"receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1","receiveType":"MRT0"},{"receiveMailAddr":"customer2@nhnent.com","receiveName":"고객2","receiveType":"MRT1"}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

응답

{
    "header": {
        "isSuccessful":boolean,
        "resultCode":Integer,
        "resultMessage":String
    },
    "body": {
        "data": {
            "requestId":String,
            "statusCode":String
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data Object 데이터 영역
-- requestId String 요청 ID
-- statusCode String 요청 상태 코드(Y: 발송준비 , N: 발송준비실패)

개별 메일 발송

  • 수신자가 여럿일 때 수신자 각각에게 메일을 발송하는 기능. 수신자는 수신인이 한 명으로 보입니다.

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/sender/eachMail

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Request body]

타입 필수 설명
​senderAddress String O 발신자 메일
senderName String X 발신자 이름
requestDate String X 발송 일자, 미입력 시 현재 시간으로 발송(yyyy-MM-dd HH:mm:ss)
title String O 제목
body String O 내용
attachFileIdList List:String X 업로드한 첨부 파일 ID
templateId String X 발송 템플릿 ID
receiverList List O 수신자 목록
최대 1,000명까지 발송 가능
- receiveMailAddr String O 수신자 메일 주소
- receiveName String X 수신자 이름
- templateParameter Object X 치환 파라미터(메일 제목/내용 치환 시 입력)
-- #key# String X 치환 키(##key##)
-- #value# Object X 치환 키에 매핑되는 값
customHeaders Map X 사용자 지정 헤더
userId String X 발송 구분자 예) admin, system

[주의]

  • template을 사용할 경우 title, body는 필수 제외(입력 시 입력된 값이 template보다 우선 적용)

  • templateParameter 인자를 사용할 때는 templateId 인자를 필수로 입력

[예시 1]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/eachMail -d '{"senderAddress":"support@nhnent.com","senderName":"발송자이름","title":"샘플 타이틀","body":"샘플 내용","attachFileIdList":["첨부파일_ID"],"receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1"}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

[예시 2 - 템플릿 사용]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/eachMail -d '{"templateId":"TEMPLATE1","receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1","templateParameter":{"key":"value"}}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

응답

{
    "header": {
        "isSuccessful":boolean,
        "resultCode":Integer,
        "resultMessage":String
    },
    "body": {
        "data": {
            "requestId":String,
            "statusCode":String
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data Object 데이터 영역
-- requestId String 요청 ID
-- statusCode String 요청 상태 코드(Y: 발송 준비 , N: 발송준비실패)

광고성 일반 메일 발송

  • URL의 끝에만 ad-mail로 바뀌며 나머지는 일반 메일 발송과 동일합니다.

광고 메일 전송 시 유의 사항

  • 제목에 반드시 (광고) 문구를 삽입합니다.
  • 자세한 내용은 광고성 메일 발송을 참고합니다.

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/sender/ad-mail

[예시 1]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/ad-mail -d '{"senderAddress":"support@nhnent.com","senderName":"발송자이름","title":"(광고) 샘플 타이틀","body":"샘플 내용 \n##BLOCK_RECEIVER_LINK## \n##EN_BLOCK_RECEIVER_LINK##","receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1","receiveType":"MRT0"},{"receiveMailAddr":"customer2@nhnent.com","receiveName":"고객2","receiveType":"MRT1"}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

[예시 2 - 템플릿 사용]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/ad-mail -d '{"templateId":"TEMPLATE1","templateParameter":{"key":"value"},"receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1","receiveType":"MRT0"},{"receiveMailAddr":"customer2@nhnent.com","receiveName":"고객2","receiveType":"MRT1"}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

광고성 개별 메일 발송

  • URL의 끝에만 ad-eachMail로 바뀌며 나머지는 개별 메일 발송과 동일합니다.

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/sender/ad-eachMail

[예시 1]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/ad-eachMail -d '{"senderAddress":"support@nhnent.com","senderName":"발송자이름","title":"(광고) 샘플 타이틀","body":"샘플 내용 \n##BLOCK_RECEIVER_LINK## \n##EN_BLOCK_RECEIVER_LINK##","attachFileIdList":["첨부파일_ID"],"receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1"}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

[예시 2 - 템플릿 사용]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/ad-eachMail -d '{"templateId":"TEMPLATE1","receiverList":[{"receiveMailAddr":"customer1@nhnent.com","receiveName":"고객1","templateParameter":{"key":"value"}}],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

태그 메일 발송

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/sender/tagMail

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Request body]

{
    "senderAddress": String,
    "senderName": String,
    "requestDate": String,
    "title": String,
    "body": String,
    "templateId": String,
    "adYn": String,
    "autoSendYn": String,
    "attachFileIdList": List:String,
    "tagExpression": List:String,
    "userId": String
}
타입 필수 설명
senderAddress String O 발신자 주소
senderName String X 발신자 이름
requestDate String X 발송 일자 미입력 시 현재 시간으로 발송(yyyy-MM-dd HH:mm:ss)
title String O 제목
body String O 내용
templateId String X 템플릿 ID
adYn String X 광고 여부(기본값 'N')
autoSendYn String X 자동 발송 여부(기본값 'Y')
attachFileIdList List:String X 첨부 파일 목록
tagExpression List:String O 태그 표현식
customHeaders Map X 사용자 지정 헤더
userId String X 발송 구분자
예) admin, system

[주의]

  • template을 사용할 경우 title, body는 필수입력 제외 (입력 시 입력된 값이 template보다 우선 적용)

[예시 1]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/tagMail -d '{"senderAddress":"support@nhnent.com","senderName":"발송자이름","title":"샘플 타이틀","body":"샘플 내용","attachFileIdList":["첨부파일_ID"],"tagExpression":["tag1","AND","tag2"],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

[예시 2 - 템플릿 사용]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/tagMail -d '{"templateId":"TEMPLATE1","tagExpression":["tag1","AND","tag2"],"customHeaders":{"X-Sample":"sample","Content-Type":"text/html; charset=utf-8"},"userId":"XXXXX"}'

응답

{
    "header": {
        "isSuccessful":boolean,
        "resultCode":Integer,
        "resultMessage":String
    },
    "body": {
        "data": {
            "requestId":String
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data Object 데이터 영역
-- requestId String 요청 ID

첨부 파일 업로드

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/attachfile/binaryUpload

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Request body]

{
    "fileName": String,
    "createUser": String,
    "fileBody": Byte[]
}
타입 필수 설명
fileName String O 파일 이름
fileBody Byte[] O 파일의 Byte[] 값
createUser String O 파일 업로드 사용자 정보

[예시]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/attachfile/binaryUpload -d '{"fileName":"file.csv","createUser":"XXXXX","fileBody":[]}'

응답

{
  "header": {
    "isSuccessful":  Boolean,
    "resultCode": Integer,
    "resultMessage": String
  },
  "body": {
    "data": {
      "requestId": String,
      "fileName": String,
      "filePath": String
    }
  }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data Object 데이터 영역
-- requestId String 임시 request ID
-- fileName String 파일 이름
-- filePath String 첨부 파일 기본 경로
(https://domain/attachFile/filePath/fileName)

제목/본문 치환

치환 기능 메일 작성 예시

* title : ##title_name## 님 안녕하세요 !!
* body : ##body_content## 발송합니다.

일반 메일 요청 예시

{
    "senderAddress" : "support@nhnent.com",
    "templateId": "template1",
    "templateParameter" : {"title_name": "클라우드고객1", "body_content": "test1"},
    "receiverList" : [
        {
            "receiveMailAddr" : "customer1@nhnent.com",
            "receiveType" : "MRT0"
        }

    ],
    "userId" : "tester"
}

개별 메일 요청 예시

{
    "senderAddress" : "support@nhnent.com",
    "templateId": "template1",
    "receiverList" : [
        {
            "receiveMailAddr" : "customer1@nhnent.com",
            "templateParameter" : {"title_name": "클라우드고객1", "body_content": "test1"}
        },
        {
            "receiveMailAddr" : "customer2@nhnent.com",
            "templateParameter" : {"title_name": "클라우드고객2", "body_content": "test2"}
        }

    ],
    "userId" : "tester"
}

결과 예시

* title : 클라우드고객1 님 안녕하세요!!
* body : test2 발송합니다.

메일 조회

메일 발송 목록 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/sender/mails

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
requestId String O 요청 ID
startSendDate String O 발송 날짜 시작값(yyyy-MM-dd HH:mm:ss)
endSendDate String X 발송 날짜 종룟값(yyyy-MM-dd HH:mm:ss)
startReceiveDate String X 수신 날짜 시작값(yyyy-MM-dd HH:mm:ss)
endReceiveDate String X 수신 날짜 종룟값(yyyy-MM-dd HH:mm:ss)
senderMail String X 발신 메일 주소
senderName String X 발신자 이름
receiveMail String X 수신 메일 주소
templateId String X 템플릿 번호
sendStatus String X 발송 상태 코드
SST0: 발송준비, SST1: 발송중,
SST2: 발송완료, SST3 : 발송실패
pageNum Integer X 페이지 번호(기본값: 1)
pageSize Integer X 조회 수(기본값: 15)

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/mails?startSendDate=2018-03-01+00%3A00&endSendDate=2018-03-07+23%3A59&pageSize=10"

응답

{
    "header": {
        "isSuccessful": boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "pageNum": Integer,
        "pageSize": Integer,
        "totalCount": Integer,
        "data": [{
            "requestId": String,
            "requestIp": String,
            "templateId": String,
            "templateName": String,
            "masterStatusCode": String,
            "mailSeq": String,
            "senderName": String,
            "senderMail": String,
            "title": String,
            "body": String,
            "resultId": String,
            "resultDate": String,
            "mailStatusCode": String,
            "mailStatusName": String,
            "requestDate": String,
            "receiverMail": String,
            "receiveType": String
        }]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- pageNum Integer 현재 페이지 번호
-pageSize Integer 조회된 데이터 수
- totalCount Integer 총 데이터 수
- data List 데이터 영역
-- requestId String 요청 ID
-- requestDate String 발신 일시
-- requestIp String 발신 서버 IP
-- resultDate String 수신 일시
-- templateId String 템플릿 ID
-- templateName String 템플릿명
-- masterStatusCode String 메일 발송 준비 상태 코드(Y: 발송준비 , N: 발송실패)
-- mailSeq String 메일 순번
-- body String 본문 내용
-- title String 메일 제목
-- senderMail String 발신자 메일 주소
-- senderName String 발신자 이름
-- receiverMail String 수신자 메일 주소
-- receiveType String 수신자 유형(MRT0: 받는사람 , MRT1: 참조, MRT2: 숨은 참조)
-- resultId String 발송 결과 ID
-- resultDate String 발송 완료 일시
-- mailStatusCode String 발송 상태 코드
SST0: 발송준비, SST1: 발송중,
SST2: 발송완료, SST3: 발송실패
-- mailStatusName String 발송 상태 이름
-- requestDate String 발송 요청 일시

메일 발송 상세 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/sender/mail/{requestId}/{mailSeq}

[Path parameter]

타입 설명
appKey String 고유의 앱키
requestId String 요청 ID
mailSeq Integer 메일 순번

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/sender/mail/{requestId}/{mailSeq}"

응답

{
    "header": {
        "isSuccessful": boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "data": {
            "requestId": String,
            "requestIp": String,
            "requestDate": String,
            "masterStatusCode": String,
            "mailStatusCode": String,
            "mailStatusName": String,
            "templateId": String,
            "templateName": String,
            "senderName": String,
            "senderMail": String,
            "title": String,
            "body": String,
            "attachFileYn": String,
            "resultId": String,
            "resultDate": String,
            "receivers": [{
                "requestId": String,
                "mailSequence": Integer,
                "receiveType": String,
                "receiveTypeName": String,
                "receiveName": String,
                "receiveMailAddr": String,
                "readYn": String,
                "readDate": String
            }],
            "attachFileList": [{
                "filePath": String,
                "fileName": String,
                "fileSize": Integer,
                "fileSequence": Integer,
                "createDate": String,
                "updateDate": String
            }],
            "customHeaders": Map
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data Object 데이터 영역
-- mailStatusCode String 발송 상태
-- mailStatusName String 발송 상태 이름
-- templateId String 템플릿 ID
-- templateName String 템플릿 이름
-- senderName String 발신자 이름
-- senderMail String 발신 메일 주소
-- title String 메일 제목
-- body String 메일 내용
-- attachFileYn String 첨부 파일 여부
-- resultId String 메일 발송 ID
-- resultDate String 발송 완료 일시
-- receivers List 수신자 목록
--- requestId String 요청ID
--- mailSequence Integer 메일 순번
--- receiveType String 수신자 유형
--- receiveTypeName String 수신자 유형명
--- receiveName String 수신자 이름
--- receiveMailAddr String 수신 메일 주소
--- readYn String 수신 여부
--- readDate String 수신 날짜(yyyy-MM-dd HH:mm:ss.SSS)
-- attachFileList List 첨부 파일 목록
--- filePath String 첨부 파일 경로
--- fileName String 첨부 파일 이름
--- fileSize Integer 첨부 파일 크기
--- fileSequence Integer 첨부 파일 순번
--- createDate String 생성 일시
--- updateDate String 수정 일시
-- customHeaders Map 사용자 지정 헤더

v1.1의 달라진 사항

  • 사용자 지정 헤더를 나타내는 customHeaders 항목이 추가되었습니다.

태그 메일 발송 요청 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/tagMails

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
requestId String O 요청 ID
startSendDate String O 발송 날짜 시작값(yyyy-MM-dd HH:mm:ss)
endSendDate String O 발송 날짜 종룟값(yyyy-MM-dd HH:mm:ss)
senderMail String X 발신 메일 주소
senderName String X 발신자 이름
templateId String X 템플릿 ID
sendStatus String X 발송 상태 코드
WAIT: 대기, READY: 발송준비,
SENDREADY: 발송준비완료, SENDWAIT: 발송대기,
SENDING: 발송중, COMPLETE: 발송완료,
FAIL: 발송실패, CANCEL: 발송취소
pageNum Integer X 페이지 번호(기본값: 1)
pageSize Integer X 조회 수(기본값: 15)

[주의]

  • requestId가 있는 경우, startSendDate와 endSendDate는 필숫값이 아닙니다.
  • startSendDate와 endSendDate가 있는 경우, requestId는 필숫값이 아닙니다.

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tagMails?startSendDate=2018-03-01+00%3A00&endSendDate=2018-03-07+23%3A59&pageSize=10"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "pageNum": Integer,
        "pageSize": Integer,
        "totalCount": Integer,
        "data": [
            {
                "requestId": String,
                "requestIp": String,
                "requestDate": String,
                "tagSendStatus": String,
                "tagExpression": List:String,
                "templateId": String,
                "templateName": String,
                "senderName": String,
                "senderMailAddress": String,
                "title": String,
                "body": String,
                "attachYn": String,
                "adYn": String,
                "createUser": String,
                "createDate": String,
                "updateUser": String,
                "updateDate": String
            }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- pageNum Integer 현재 페이지 번호
-pageSize Integer 조회된 데이터 수
- totalCount Integer 총 데이터 수
- data List 데이터 영역
-- requestId String 요청 ID
-- requestIp String 요청 IP
-- requestDate String 요청 시간
-- tagSendStatus String 발송 상태 코드
WAIT: 대기, READY: 발송준비,
SENDREADY: 발송준비완료, SENDWAIT: 발송대기,
SENDING: 발송중, COMPLETE: 발송완료,
FAIL: 발송실패, CANCEL: 발송취소
-- tagExpression List:String 태그 표현식
-- templateId String 템플릿 ID
-- templateName String 템플릿명
-- senderName String 발신자 이름
-- senderMail String 발신자주소
-- title String 제목
-- body String 내용
-- attachYn String 첨부 파일 여부
-- adYn String 광고 여부
-- createUser String 생성자
-- createDate String 생성 일시
-- updateUser String 수정자
-- updateDate String 수정 일시

태그 메일 발송 수신자 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/tagMails/{requestId}

[Path parameter]

타입 설명
appKey String 고유의 앱키
requestId String 요청 ID

[Query parameter]

타입 필수 설명
receiveMail String X 수신 메일 주소
startReceiveDate String X 수신 날짜 시작값(yyyy-MM-dd HH:mm:ss)
endReceiveDate String X 수신 날짜 종룟값(yyyy-MM-dd HH:mm:ss)
receiveStatus String X 발송 상태 코드
SST0: 발송준비, SST1: 발송중,
SST2: 발송완료, SST3 : 발송실패
pageNum Integer X 페이지 번호(기본값: 1)
pageSize Integer X 조회 수(기본값: 15)

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tagMails/{requestId}?startReceiveDate=2018-03-01+00%3A00&endReceiveDate=2018-03-07+23%3A59&pageSize=10"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "pageNum": Integer,
        "pageSize": Integer,
        "totalCount": Integer,
        "data": [
            {
                "requestId": String,
                "mailSequence": Integer,
                "receiveMail": String,
                "mailStatusCode": String,
                "mailStatusName": String,
                "resultId": String,
                "resultDate": String,
                "readYn": String,
                "readDate": String,
                "createUser": String,
                "createDate": String,
                "updateUser": String,
                "updateDate": String
            }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- pageNum Integer 현재 페이지 번호
-pageSize Integer 조회된 데이터 수
- totalCount Integer 총 데이터 수
- data List 데이터 영역
-- requestId String 요청 ID
-- mailSequence Integer 메일 순번
-- receiveMail String 수신자 주소
-- mailStatusCode String 메일 상태 코드
SST0: 발송준비, SST1: 발송중,
SST2: 발송완료, SST3 : 발송실패
-- mailStatusName String 메일 상태 이름
-- resultId String SMTP ID
-- resultDate String 실제 발송 시간
-- readYn String 읽음 여부
-- readDate String 읽은 시간
-- createUser String 생성자
-- createDate String 생성 일시
-- updateUser String 수정자
-- updateDate String 수정 일시

태그 메일 발송 상세 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/tagMails/{requestId}/{mailSequence}

[Path parameter]

타입 설명
appKey String 고유의 앱키
requestId String 요청 ID
mailSequence Integer 메일 순번

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tagMails/{requestId}/{mailSequence}"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "data": {
            "requestId": String,
            "requestIp": String,
            "templateId": String,
            "templateName": String,
            "mailStatusCode": String,
            "mailStatusName": String,
            "requestDate": String,
            "resultDate": String,
            "senderName": String,
            "senderMail": String",
            "resultId": String,
            "title": String,
            "body": String",
            "receivers": [
                {
                    "requestId": String
                    "mailSequence": String
                    "receiveType": String
                    "receiveTypeName": String
                    "receiveMailAddr": String
                    "readYn": String
                    "readDate": String
                }
            ],
            "attachFileList": [
                {
                    "filePath": String
                    "fileName": String
                    "fileSize": Integer,
                    "fileSequence": Integer,
                    "createDate": String
                    "updateDate": String
                }
            ],
            "customHeaders": Map
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- pageNum Integer 현재 페이지 번호
-pageSize Integer 조회된 데이터 수
- totalCount Integer 총 데이터 수
- data List 데이터 영역
-- requestId String 요청 ID
-- requestIp String 요청 IP
-- templateId String 템플릿 ID
-- templateName String 템플릿 이름
-- mailStatusCode String 메일 상태 코드
SST0: 발송준비, SST1: 발송중,
SST2: 발송완료, SST3 : 발송실패
-- mailStatusName String 메일 상태 이름
-- requestDate String 요청 시간
-- resultDate String 결과 시간
-- senderName String 발신자 이름
-- senderMail String 발신자 주소
-- resultId String SMTP ID
-- title String 제목
-- body String 내용
-- receivers List 수신자 목록
--- requestId String 요청 ID
--- mailSequence Integer 메일 순번
--- receiveType String 수신자 유형(MRT0: 받는 사람, MRT1: 참조, MRT2: 숨은 참조)
--- receiveTypeName String 수신자 유형 이름
--- receiveMailAddr String 수신자 메일 주소
--- readYn String 읽음 여부
--- readDate String 읽은 시간
-- attachFileList List 첨부 파일 목록
--- filePath String 파일 경로
--- fileName String 파일 명
--- fileSize Long 파일 사이즈
--- fileSequence Integer 파일 번호
--- createDate String 파일 생성 일시
--- updateDate String 파일 수정 일시
-- customHeaders Map 사용자 지정 헤더(v1.1부터 필드 추가)

v1.1의 달라진 사항

  • 사용자 지정 헤더를 나타내는 customHeaders 항목이 추가되었습니다.

템플릿 조회

템플릿 목록 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/templates

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
categoryId Integer X 카테고리 ID
useYn String X 사용 여부(Y/N)
pageNum Integer X 페이지 번호(기본값: 1)
pageSize Integer X 조회 수(기본값: 15)
all Boolean X 전체 템플릿 목록 조회 여부

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/templates?useYn=Y&pageNum=1&pageSize=10"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "pageNum": Integer,
        "pageSize": Integer,
        "totalCount": Integer,
        "data": [{
            "templateId": String,
            "serviceId": Integer,
            "categoryId": Integer,
            "categoryName": String,
            "sort": Integer,
            "templateName": String,
            "templateDesc": String,
            "useYn": String,
            "sendMailAddress": String,
            "sendType": String,
            "sendTypeName": String,
            "title": String,
            "body": String,
            "attachFileYn": String,
            "delYn": String,
            "createDate": String,
            "createUser": String,
            "updateDate": String,
            "updateUser": String,
}]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- pageNum Integer 현재 페이지 번호
-pageSize Integer 조회된 데이터 수
- totalCount Integer 총 데이터 수
-data List 데이터 영역
--templateId String 템플릿 ID
--serviceId Integer 서비스 ID
--categoryId Integer 카테고리 ID
--categoryName String 카테고리 이름
--sort Integer 순서
--templateName String 템플릿 이름
--templateDesc String 템플릿 설명
-- useYn String 사용 여부
--sendMailAddress String 템플릿 발신 메일 주소
--title String 메일 제목
--body String 메일 본문
--attachFileYn String 템플릿 첨부 파일 추가 여부
--delYn String 삭제 여부
--createDate String 생성 일시
--updateDate String 수정 일시

템플릿 상세 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/templates/{templateId}

[Path parameter]

타입 설명
appKey String 고유의 앱키
templateId String 템플릿 ID

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/templates/{templateId}"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
    "data": [{
            "templateId": String,
            "serviceId": Integer,
            "categoryId": Integer,
            "categoryName": String,
            "templateName": String,
            "templateDesc": String,
            "useYn": String,
            "sendMailAddress": String,
            "title": String,
            "body": String,
            "delYn": String,
            "createDate": String,
            "createUser": String,
            "updateDate": String,
            "updateUser": String,
            "attachFileList": [{
                "fileId": Integer,
                "serviceId" : Integer,
                "templateId": String,
                "filePath": String,
                "fileName": String,
                "fileSize" : Integer,
                "createDate": String,
                "createUser": String,
                "updateDate" : String,
                "updateUser" : String
            }]
        }]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
-data List 데이터 영역
--templateId String 템플릿 ID
--serviceId Integer 서비스 ID
--categoryId Integer 카테고리 ID
--categoryName String 카테고리 이름
--templateName String 템플릿 이름
--templateDesc String 템플릿 설명
--useYn String 사용 여부(Y:사용 중, N: 사용 안 함)
--sendMailAddress String 발신 메일 주소
--title String 메일 주소
--body String 메일 내용
--delYn String 삭제 여부
--createDate String 생성 일시
--createUser String 생성자
--updateDate String 수정 일시
--updateUser String 수정자
--attachFileList List 첨부 파일 목록
---fileId Integer 첨부 파일 ID
---serviceId Integer 서비스 ID
---templateId String 템플릿 ID
---filePath String 첨부 파일 경로
---fileName String 첨부 파일 이름
---fileSize Integer 첨부 파일 크기
---createDate String 생성 일시
---createUser String 생성자
---updateDate String 수정 일시
---updateUser String 수정자

태그 관리

태그 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/tags

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
pageNum Integer X 페이지 번호(기본값: 1)
pageSize Integer X 조회 수(기본값: 15)

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tags?pageNum=1&pageSize=10"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "pageNum": Integer,
        "pageSize": Integer,
        "totalCount": Integer,
        "data": [
            {
                "tagId": String,
                "tagName": String,
                "createdDate": String,
                "updatedDate": String
            }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- tagId String 태그 ID
-- tagName String 태그 이름
-- createdDate String 생성 일시
-- updatedDate String 수정 일시

태그 등록

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/tags

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Request body]

타입 필수 설명
tagName String O 태그 이름

[예시]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tags -d '{"tagName":"샘플태그"}'

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "data": {
            "tagId": String
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- tagId String 태그 ID

태그 수정

요청

[URL]

Http method URI
PUT /email/v1.1/appKeys/{appKey}/tags/{tagId}

[Path parameter]

타입 설명
appKey String 고유의 앱키
tagId String 태그 ID

[Request body]

타입 필수 설명
tagName String O 태그 이름

[예시]

curl -X PUT -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tags/{tagId} -d '{"tagName":"샘플태그2"}'

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

태그 삭제

요청

[URL]

Http method URI
DELETE /email/v1.1/appKeys/{appKey}/tags/{tagId}

[Path parameter]

타입 설명
appKey String 고유의 앱키
tagId String 태그 ID

[예시]

curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/tags/{tagId}

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

UID 관리

UID 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/uids

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
wheres List:String X 조회 조건.
알파벳, 숫자, 괄호로 이루어진 문자열 배열.
괄호는 1개, AND, OR는 3개까지 사용할 수 있다.
예) tagId1,AND,tagId2
offsetUid String X offset UID
offset Integer X offset(기본값: 0)
limit Integer X 조회 수(기본값: 15)

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/uids?wheres=tagId1,OR,tagId2&offset=0&limit=10"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "data": {
            "uids": [
                {
                    "uid": String,
                    "tags": [
                        {
                            "tagId": String,
                            "tagName": String,
                            "createDate": String,
                            "updateDate": String
                        }
                    ],
                    "contacts": [
                        {
                            "contactType": String,
                            "contact": String,
                            "createDate": String"
                        }
                    ]
                }
            ],
            "isLast": Boolean,
            "totalCount": Integer
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- uids List UID 목록
--- uid String UID
--- tags List 태그 정보 목록
---- tagId String 태그 ID
---- tagName String 태그 이름
---- createDate String 태그 생성 일시
---- updateDate String 태그 수정 일시
--- contacts List 연락처 목록
---- contactType String 연락처 유형(EMAIL_ADDRESS)
---- contact String 연락처(메일 주소)
---- createDate String 연락처 생성 일시
-- isLast Boolean 마지막 목록 여부
-- totalCount Integer 총 데이터 수

UID 단건 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/uids/{uid}

[Path parameter]

타입 설명
appKey String 고유의 앱키
uid String UID

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/uids/{uid}"

응답

{
    "header": {
        "isSuccessful": String,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "data": {
            "uid": "",
            "tags": [
                {
                    "tagId": String,
                    "tagName": String,
                    "createDate": String,
                    "updateDate": String
                }
            ],
            "contacts": [
                {
                    "contactType": String,
                    "contact": String,
                    "createDate": String
                }
            ]
        }
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- uid String UID
-- tags List 태그 정보 목록
--- tagId String 태그 ID
--- tagName String 태그 이름
--- createDate String 태그 생성 일시
--- updateDate String 태그 수정 일시
-- contacts List 연락처 목록
--- contactType String 연락처 유형
--- contact String 연락처(메일 주소)
--- createDate String 연락처 생성 일시

UID 등록

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/uids

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Request body]

타입 필수 설명
uid String O UID
tagIds List:String O 태그 ID 목록
contacts List O 메일 주소 목록
-contactType String O 연락처 유형
-contact String O 연락처(메일 주소)

[주의]

  • tagIds가 주어지는 경우 contacts는 필숫값이 아닙니다.
  • contacts가 주어지는 경우 tagIds는 필숫값이 아닙니다.
  • 본 상품의 경우, contactType은 반드시 "EMAIL_ADDRESS"값으로 요청해야 합니다.

[예시]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/uids -d '{"uids":[{"uid":"sample-uid","tagIds":["tagId1"],"contacts":[{"contactType":"EMAIL_ADDRESS","contact":"customer1@nhnent.com"},{"contactType":"EMAIL_ADDRESS","contact":"customer2@nhnent.com"}]}]}'

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

UID 삭제

요청

[URL]

Http method URI
DELETE /email/v1.1/appKeys/{appKey}/uids/{uid}

[Path parameter]

타입 설명
appKey String 고유의 앱키
uid String UID

[예시]

curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/uids/{uid}

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

메일 주소 등록

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/uids/{uid}/email-addresses

[Path parameter]

타입 설명
appKey String 고유의 앱키
uid String UID

[Request body]

타입 필수 설명
emailAddress String O 메일 주소

[예시]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/uids/{uid}/email-addresses -d '{"emailAddress" : "customer1@nhnent.com"}'

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

메일 주소 삭제

요청

[URL]

Http method URI
DELETE /email/v1.1/appKeys/{appKey}/uids/{uid}/email-addresses/{emailAddress}

[Path parameter]

타입 설명
appKey String 고유의 앱키
uid String UID
emailAddress String 메일 주소

[예시]

curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/uids/{uid}/email-addresses/customer1@nhnent.com

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

통계 조회

일별 통계 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/statistics/daily

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
from String O 통계 조회 시작 날짜(년-월-일)
(yyyy-MM-dd)
to String O 통계 조회 종료 날짜(년-월-일)
(yyyy-MM-dd)
type String X 조회 타입
REQUEST:요청
SENT: 발송
RECEIVED :수신
OPENED:오픈
filters String X 검색 조건(다중 파라미터 가능)
MAILTYPE:메일타입별(일반/대량) 통계
TEMPLATE:템플릿별 통계

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/statistics/daily?from=2018-03-01&to=2018-03-07&type=OPENED&filters=MAILTYPE&filters=TEMPLATE"

응답

{
    "isSuccessful": Boolean,
    "resultCode": Integer,
    "resultMessage": String
},
    "body" : {
        "data" : [
        {
            "ymd" :  String,
            "appKey" :  String,
            "type" :  String,
            "mailType" :  String,
            "templateId" :  String,
            "templateName" :  String,
            "tm00" :  int,
            "tm01" :  int,
            "tm02" :  int,
            "tm03" :  int,
            "tm04" :  int,
            "tm05" :  int,
            "tm06" :  int,
            "tm07" :  int,
            "tm08" :  int,
            "tm09" :  int,
            "tm10" :  int,
            "tm11" :  int,
            "tm12" :  int,
            "tm13" :  int,
            "tm14" :  int,
            "tm15" :  int,
            "tm16" :  int,
            "tm17" :  int,
            "tm18" :  int,
            "tm19" :  int,
            "tm20" :  int,
            "tm21" :  int,
            "tm22" :  int,
            "tm23" :  int,
            "sum" : int
        }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- ymd String 통계 날짜(yyyyMMdd)
-- appKey String 앱키
-- type String 통계 조회 유형
REQUEST:요청
SENT: 발송
RECEIVED:수신
OPENED:오픈
-- mailType String 메일 유형
MAILTYPE: 메일 유형별(일반/대량) 통계
TEMPLATE: 템플릿별 통계
-- templateId String 템플릿 ID
-- templateName String 템플릿 이름
-- tm00 int 00:00:00 ~ 00:59:59
-- tm01 int 01:00:00 ~ 01:59:59
-- tm02 int 02:00:00 ~ 02:59:59
-- tm03 int 03:00:00 ~ 03:59:59
-- tm04 int 04:00:00 ~ 04:59:59
-- tm05 int 05:00:00 ~ 05:59:59
-- tm06 int 06:00:00 ~ 06:59:59
-- tm07 int 07:00:00 ~ 07:59:59
-- tm08 int 08:00:00 ~ 08:59:59
-- tm09 int 09:00:00 ~ 09:59:59
-- tm10 int 10:00:00 ~ 10:59:59
-- tm11 int 11:00:00 ~ 11:59:59
-- tm12 int 12:00:00 ~ 12:59:59
-- tm13 int 13:00:00 ~ 13:59:59
-- tm14 int 14:00:00 ~ 14:59:59
-- tm15 int 15:00:00 ~ 15:59:59
-- tm16 int 16:00:00 ~ 16:59:59
-- tm17 int 17:00:00 ~ 17:59:59
-- tm18 int 18:00:00 ~ 18:59:59
-- tm19 int 19:00:00 ~ 19:59:59
-- tm20 int 20:00:00 ~ 20:59:59
-- tm21 int 21:00:00 ~ 21:59:59
-- tm22 int 22:00:00 ~ 22:59:59
-- tm23 int 23:00:00 ~ 23:59:59
-- sum int 합계

월별 통계 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/statistics/monthly

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
from String O 통계 조회 시작 날짜(년-월)
(yyyy-MM)
to String O 통계 조회 종료 날짜(년-월)
(yyyy-MM)
type String X 조회 유형
REQUEST: 요청
SENT: 발송
RECEIVED: 수신
OPENED: 오픈
filters String X 검색 조건(다중 파라미터 가능)
MAILTYPE: 메일 유형별(일반/대량) 통계
TEMPLATE: 템플릿별 통계

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/statistics/monthly?from=2018-03&to=2018-04&type=OPENED&filters=MAILTYPE&filters=TEMPLATE"

응답

{
    "isSuccessful": Boolean,
    "resultCode": Integer,
    "resultMessage": String
},
    "body" : {
        "data" : [
        {
            "ymd" :  String,
            "appKey" :  String,
            "type" :  String,
            "mailType" :  String,
            "templateId" :  String,
            "templateName" :  String,
            "tm00" :  int,
            "tm01" :  int,
            "tm02" :  int,
            "tm03" :  int,
            "tm04" :  int,
            "tm05" :  int,
            "tm06" :  int,
            "tm07" :  int,
            "tm08" :  int,
            "tm09" :  int,
            "tm10" :  int,
            "tm11" :  int,
            "tm12" :  int,
            "tm13" :  int,
            "tm14" :  int,
            "tm15" :  int,
            "tm16" :  int,
            "tm17" :  int,
            "tm18" :  int,
            "tm19" :  int,
            "tm20" :  int,
            "tm21" :  int,
            "tm22" :  int,
            "tm23" :  int,
            "sum" : int
        }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- ymd String 통계 날짜(yyyyMMdd)
-- appKey String 앱키
-- type String 통계 조회 유형
REQUEST: 요청
SENT: 발송
RECEIVED: 수신
OPENED: 오픈
-- mailType String 메일 유형
MAILTYPE:메일 유형별(일반/대량) 통계
TEMPLATE:템플릿별 통계
-- templateId String 템플릿 ID
-- templateName String 템플릿 이름
-- tm00 int 00:00:00 ~ 00:59:59
-- tm01 int 01:00:00 ~ 01:59:59
-- tm02 int 02:00:00 ~ 02:59:59
-- tm03 int 03:00:00 ~ 03:59:59
-- tm04 int 04:00:00 ~ 04:59:59
-- tm05 int 05:00:00 ~ 05:59:59
-- tm06 int 06:00:00 ~ 06:59:59
-- tm07 int 07:00:00 ~ 07:59:59
-- tm08 int 08:00:00 ~ 08:59:59
-- tm09 int 09:00:00 ~ 09:59:59
-- tm10 int 10:00:00 ~ 10:59:59
-- tm11 int 11:00:00 ~ 11:59:59
-- tm12 int 12:00:00 ~ 12:59:59
-- tm13 int 13:00:00 ~ 13:59:59
-- tm14 int 14:00:00 ~ 14:59:59
-- tm15 int 15:00:00 ~ 15:59:59
-- tm16 int 16:00:00 ~ 16:59:59
-- tm17 int 17:00:00 ~ 17:59:59
-- tm18 int 18:00:00 ~ 18:59:59
-- tm19 int 19:00:00 ~ 19:59:59
-- tm20 int 20:00:00 ~ 20:59:59
-- tm21 int 21:00:00 ~ 21:59:59
-- tm22 int 22:00:00 ~ 22:59:59
-- tm23 int 23:00:00 ~ 23:59:59
-- sum int 합계

통합 통계 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/statistics/view

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
from String O 통계 조회 시작 날짜
yyyy-mm-dd HH:mm
to String O 통계 조회 종료 날짜
yyyy-mm-dd HH:mm
searchType String O 통계 구분
DATE: 날짜별, TIME: 시간별, DAY: 요일별
mailTypes String X 메일 타입
NORMAL: 일반, MASS: 대량
복수 입력 가능(mailTypes=NORMAL&mailTypes=MASS)
adYn String X 광고 여부
Y:광고, N:광고 아님
입력하지 않으면 전체
templateId String X 템플릿 ID

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/statistics/view?from=2018-03-21+00%3A00&to=2018-03-23+00%3A00&searchType=DATE&mailTypes=NORMAL&templateId=templateId1"

응답

{
    "isSuccessful": Boolean,
    "resultCode": Integer,
    "resultMessage": String
},
    "body" : {
        "data" : [
          {
                  "divisionName": String,
                  "requestedCount": long,
                  "sentCount": long,
                  "receivedCount": long,
                  "openedCount": long,
                  "sentRate": String,
                  "receivedRate": String,
                  "openedRate": String
        }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- data List 데이터 영역
-- divisionName String 통계 기준(날짜/시간/요일)
-- requestedCount Long 발송 요청 건수
-- sentCount Long 발송 건수
-- receivedCount Long 수신 건수
-- openedCount Long 오픈 건수
-- sentRate String 발송률
-- receivedRate String 수신율
-- openedRate String 오픈율

수신 거부 관리

수신 거부 조회

요청

[URL]

Http method URI
GET /email/v1.1/appKeys/{appKey}/block-receivers

[Path parameter]

타입 설명
appKey String 고유의 앱키

[Query parameter]

타입 필수 설명
mailAddress String X 수신 거부 목록에 등록되어 있는 이메일 주소
pageNum Integer X 페이지 번호(기본값: 1)
pageSize Integer X 조회 수(기본값: 15)

[예시]

curl -X GET -H "Content-Type: application/json;charset=UTF-8" "https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/block-receivers?mailAddress=customer1@nhnent.com&pageNum=1&pageSize=10"

응답

{
    "header": {
        "isSuccessful": Boolean,
        "resultCode": Integer,
        "resultMessage": String
    },
    "body": {
        "totalCount": Integer,
        "data": [
            {
                "mailAddress": String,
                "blockDate": String
            }
        ]
    }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
body Object 본문 영역
- pageNum Integer 현재 페이지 번호
-pageSize Integer 조회된 데이터 수
- totalCount Integer 총 데이터 수
- data List 데이터 영역
-- mailAddress String 수신 거부 이메일 주소
-- blockDate String 수신 거부 날짜(yyyy-MM-dd HH:mm:ss.S)

수신 거부 등록

요청

[URL]

Http method URI
POST /email/v1.1/appKeys/{appKey}/block-receivers

[Request body]

타입 필수 설명
blockReceiverList ㅣList O 수신 거부 목록
- mailAddress String O 수신 거부 이메일 주소
- blockDate String X 수신 거부 날짜(yyyy-MM-dd HH:mm:ss)

[예시]

curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/block-receivers -d '{"blockReceiverList":[{"mailAddress":"customer1@nhnent.com","blockDate":"2018-03-01 00:00:00"}]}'

응답

{
  "header": {
    "isSuccessful":  Boolean,
    "resultCode": Integer,
    "resultMessage": String
  }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지

수신 거부 삭제

요청

[URL]

Http method URI
PUT /email/v1.1/appKeys/{appKey}/block-receivers

[Request body]

타입 필수 설명
deleted Boolean O 수신 거부 삭제를 명시하는 필드
blockReceiverList ㅣList O 수신 거부 목록
- mailAddress String O 수신 거부 이메일 주소

[예시]

curl -X PUT -H "Content-Type: application/json;charset=UTF-8" https://api-mail.cloud.toast.com/email/v1.1/appKeys/{appKey}/block-receivers -d '{"deleted":true,"blockReceiverList":[{"mailAddress":"customer1@nhnent.com"}]}'

응답

{
  "header": {
    "isSuccessful":  Boolean,
    "resultCode": Integer,
    "resultMessage": String
  }
}
타입 설명
header Object 헤더 영역
- isSuccessful Boolean 성공 여부
- resultCode Integer 실패 코드
- resultMessage String 실패 메시지
TOP