---
title: "Cloud Outbound Mailer 개요"
slug: "ai-application-service-cloudoutboundmailer"
tags: ["Cloud Outbound Mailer"]
updated: 2026-09-17T09:10:03Z
published: 2026-09-17T09:10:03Z
canonical: "api-fin.ncloud-docs.com/ai-application-service-cloudoutboundmailer"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api-fin.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Outbound Mailer 개요

Classic/VPC 환경에서 이용 가능합니다.

## 개요

Cloud Outbound Mailer API는 RESTful 형태로 제공됩니다. HTTP 방식의 GET/POST/DELETE 메서드 호출을 통해서 이루어집니다. API를 통해 주소록을 구성/관리하고 메일 발송을 요청하며 요청 결과를 확인하고 발송 이력을 조회할 수 있습니다.

## 공통 설정

### Cloud Outbound Mailer API URL

| 리전 | 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/ |

```

### 요청 헤더<a name="요청헤더"></a>

|          헤더명         | 설명                            |
|------------------|------------------------------------------------|
|   x-ncp-apigw-timestamp  | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 나타내며 API Gateway 서버와 시간 차가 5분 이상 나는 경우 유효하지 않은 요청으로 간주<br /> ```x-ncp-apigw-timestamp:{Timestamp}``` |
|   x-ncp-iam-access-key   | NAVER Cloud Platform 포털에서 발급받은 Access Key ID 값<br/> ```x-ncp-iam-access-key:{Account Access Key}```                                                                                                        |
| x-ncp-apigw-signature-v2 | Access Key ID 값 과 Secret Key 로 암호화한 서명<br/> ```x-ncp-apigw-signature-v2:{API Gateway Signature}```                                                                                                           |
|   x-ncp-lang             | API 응답 값의 다국어 처리를 위한 값. (입력 값 예시: ko-KR, en-US, zh-CN, 기본 값:en-US)<br/> ```x-ncp-lang:{language code}```                                                                                  |

#### 인증 헤더<a name="인증헤더"></a>

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)를 참고 부탁드립니다.

- 인증키 생성
  - N네이버 클라우드 플랫폼 콘솔의 우측 상단 **My Account** > **계정 및 보안 관리** > **보안 관리** > **접근 관리** > **API 인증키**메뉴에서 **신규 API 인증키 생성**을 클릭하여 Access Key ID, Secret Key를 생성합니다
  - 만약 Access Key ID, Secret Key가 있다면 해당 키를 사용합니다.

#### 요청 예시<a name="요청예시"></a>
```

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.fin-ntruss.com/api/v1/mails" -d '{"senderAddress":"no_reply@company.com","title":"${customer_name}님 반갑습니다.${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`로 사용합니다.

-  **샘플 코드**

```java
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 | 77101 | 로그인 정보 오류 |
| 400 | 77102 | BAD_REQUEST |
| 400 | 77103 | 리소스가 존재하지 않음 |
| 403 | 77201 | 권한 없음 |
| 403 | 77202 | Email 상품 사용신청 하지 않음 |
| 405 | 77001 | METHOD_NOT_ALLOWED |
| 415 | 77002 | UNSUPPORTED_MEDIA_TYPE |
| 500 | 77301 | 기본 프로젝트가 존재하지 않음 |
| 500 | 77302 | 외부 시스템 API 연동 오류 |
| 500 | 77303 | 그외 INTERNAL_SERVER_ERROR |

참고

네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [Ncloud API 응답 상태 코드](/docs/common-ncpapi#%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)