--- title: "Cloud Outbound Mailer 개요" slug: "ai-application-service-cloudoutboundmailer" tags: ["Cloud Outbound Mailer", "overview"] updated: 2026-09-17T09:15:58Z published: 2026-09-17T09:15:58Z canonical: "api.ncloud-docs.com/ai-application-service-cloudoutboundmailer" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Cloud Outbound Mailer 개요 ## 개요 Cloud Outbound Mailer API는 RESTful 형태로 제공됩니다. HTTP 방식의 GET/POST/DELETE 메서드 호출을 통해서 이루어집니다. API를 통해 주소록을 구성/관리하고 메일 발송을 요청하며 요청 결과를 확인하고 발송 이력을 조회할 수 있습니다. ## 공통 설정 ### Cloud Outbound Mailer API Endpoint | 리전 | Endpoint | | --- | --- | | 한국(KR) | https://mail.apigw.ntruss.com/api/v1 | | 싱가폴(SGN) | https://mail.apigw.ntruss.com/api/v1-sgn/ | | 일본(JPN) | https://mail.apigw.ntruss.com/api/v1-jpn/ | ### 요청 헤더 | 헤더명 | 설명 | | --- | --- | | x-ncp-apigw-timestamp | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타내며 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주 `x-ncp-apigw-timestamp:{Timestamp}` | | x-ncp-iam-access-key | NAVER Cloud Platform 포털에서 발급받은 Access Key ID 값 `x-ncp-iam-access-key:{Account Access Key}` | | x-ncp-apigw-signature-v2 | Access Key ID 값 과 Secret Key 로 암호화한 서명 `x-ncp-apigw-signature-v2:{API Gateway Signature}` | | x-ncp-lang | API 응답 값의 다국어 처리를 위한 값. (입력 값 예시: ko-KR, en-US, zh-CN, 기본 값:en-US) `x-ncp-lang:{language code}` | #### 인증 헤더 Cloud Outbound Mailer API는 NAVER Cloud Platform API Gateway를 통하여 제공되며, API Gateway에 등록된 API를 사용하기 위해서는 2가지 인증키(Access Key ID, Secret Key)를 발급받아야 합니다 자세한 내용은 [NAVER CLOUD PLATFORM API 가이드](/docs/common-ncpapi)를 참조해 주십시오. - 인증키 생성 - [Ncloud API](https://api.ncloud-docs.com/release-20260917/docs/common-ncpapi) 를 참조하여 Access Key ID, Secret Key를 생성합니다 - 만약 Access Key ID, Secret Key가 있다면 해당 키를 사용합니다. #### 요청 예시 ``` curl -i -s -X POST \ -H "Content-Type:application/json" \ -H "x-ncp-apigw-timestamp:1521787414578" \ -H "x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy" \ -H "x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=" \ "https://mail.apigw.ntruss.com/api/v1/mails"\ -d '{"senderAddress":"no_reply@company.com","title":"${customer_name}님 반갑습니다. ","body":"귀하의 등급이 ${BEFORE_GRADE}에서 ${AFTER_GRADE}로 변경되었습니다.","recipients":[{"address":"hongildong@naver_.com","name":"홍길동","type":"R","parameters":{"customer_name":"홍길동","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"철수","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}' ``` - Signature 생성(개행 문자는 `\n`을 사용) - 요청에 맞게 StringToSign을 생성하고 SecretKey로 HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩합니다 - 이 값을 `x-ncp-apigw-signature-v2`로 사용합니다. - **샘플 코드** ``` public String makeSignature() { String space = " "; // 공백 String newLine = "\n"; // 줄바꿈 String method = "POST"; // HTTP 메소드 String url = "/api/v1/mails"; // 도메인을 제외한 "/" 아래 전체 url (쿼리스트링 포함) String timestamp = "{timestamp}"; // 현재 타임스탬프 (epoch, millisecond) String accessKey = "{accessKey}"; // access key id (from portal or sub account) String secretKey = "{secretKey}"; // secret key (from portal or sub account) String message = new StringBuilder() .append(method) .append(space) .append(url) .append(newLine) .append(timestamp) .append(newLine) .append(accessKey) .toString(); SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(signingKey); byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8")); String encodeBase64String = Base64.getEncoder().encodeToString(rawHmac); return encodeBase64String; } ``` ``` function makeSignature() { $space = " "; // 공백 $newLine = "\n"; // 줄바꿈 $method = "POST"; // HTTP 메소드 $uri= "/api/v1/mails"; // 도메인을 제외한 "/" 아래 전체 url (쿼리스트링 포함) $timestamp = "{timestamp}"; // 현재 타임스탬프 (epoch, millisecond) $accessKey = "{accessKey}"; // access key id (from portal or sub account) $secretKey = "{secretKey}"; // secret key (from portal or sub account) $hmac = $method.$space.$uri.$newLine.$timestamp.$newLine.$accessKey; $signautue = base64_encode(hash_hmac('sha256', $hmac, $secretKey,true)); return $signautue; } ``` ### 응답 공통 응답 형식을 설명합니다. #### 응답 상태 코드 응답 상태 코드에 대한 설명은 다음과 같습니다. | HTTP Status Code | 리턴 코드 | 설명 | | --- | --- | --- | | 200 | - | 일반적인 요청 성공 | | 201 | - | 리소스 생성 성공에 대한 응답 코드 | | 400 | - | 인증 실패, 잘못된 요청 | | 400 | 77101 | 로그인 정보 오류 | | 400 | 77102 | BAD_REQUEST | | 400 | 77103 | 리소스가 존재하지 않음 | | 403 | 77201 | 권한 없음 | | 403 | 77202 | Email 상품 사용신청 하지 않음 | | 405 | 77001 | METHOD_NOT_ALLOWED | | 415 | 77002 | UNSUPPORTED_MEDIA_TYPE | | 500 | - | 서버 오류 | | 500 | 77301 | 기본 프로젝트가 존재하지 않음 | | 500 | 77302 | 외부 시스템 API 연동 오류 | | 500 | 77303 | 그외 INTERNAL_SERVER_ERROR | 참고 네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud API 응답 상태 코드](/docs/common-ncpapi#3%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오. ## 오퍼레이션 ### 이메일 발송 - [createMailRequest](/docs/ai-application-service-cloudoutboundmailer-createmailrequest) - [getMail](/docs/ai-application-service-cloudoutboundmailer-getmail) - [getMailList](/docs/ai-application-service-cloudoutboundmailer-getmaillist) - [getMailRequestList](/docs/ai-application-service-cloudoutboundmailer-getmailrequestlist) - [getMailRequestStatus](/docs/ai-application-service-cloudoutboundmailer-getmailrequeststatus) - [createFile](/docs/ai-application-service-cloudoutboundmailer-createfile) - [getFile](/docs/ai-application-service-cloudoutboundmailer-getfile) - [deleteFile](/docs/ai-application-service-cloudoutboundmailer-deletefile) ### 템플릿 관리 - [createTemplate](/docs/ai-application-service-cloudoutboundmailer-createtemplate) - [getTemplate](/docs/ai-application-service-cloudoutboundmailer-gettemplate) - [getTemplateStructure](/docs/ai-application-service-cloudoutboundmailer-gettemplatestructure) - [updateTemplate](/docs/ai-application-service-cloudoutboundmailer-updatetemplate) - [deleteTemplate](/docs/ai-application-service-cloudoutboundmailer-deletetemplate) - [restoreTemplate](/docs/ai-application-service-cloudoutboundmailer-restoretemplate) - [createCategory](/docs/ai-application-service-cloudoutboundmailer-createcategory) - [deleteCategory](/docs/ai-application-service-cloudoutboundmailer-deletecategory) ### 수신자 그룹 관리 - [createAddressBook](/docs/ai-application-service-cloudoutboundmailer-createaddressbook) - [getAddressBook](/docs/ai-application-service-cloudoutboundmailer-getaddressbook) - [deleteAddressBook](/docs/ai-application-service-cloudoutboundmailer-deleteaddressbook) - [deleteAddress](/docs/ai-application-service-cloudoutboundmailer-deleteaddress) - [deleteRecipientGroup](/docs/ai-application-service-cloudoutboundmailer-deleterecipientgroup) ### 발송 차단 및 수신 거부 관리 - [getSendBlockList](/docs/ai-application-service-cloudoutboundmailer-getsendblocklist) - [registerUnsubscribers](/docs/ai-application-service-cloudoutboundmailer-registerunsubscribers) - [deleteUnsubscribers](/docs/ai-application-service-cloudoutboundmailer-deleteunsubscribers)