Cloud Outbound Mailer Overview

Overview

Cloud Outbound Mailer API is provided as a RESTful API. Calls are made via HTTP request methods such as GET, POST, and DELETE. Through this API, you can configure and manage address books, request to send emails, check request results, and view sending history.

Common settings

Cloud Outbound Mailer API Endpoint

Request headers

Authentication header

The Cloud Outbound Mailer API is provided through the NAVER Cloud Platform API Gateway, and two authentication keys (access key ID and secret key) are required to use an API registered in the API Gateway.

For more information, refer to the NAVER Cloud Platform API Guide.

• Generate authentication key
  • From the NAVER Cloud Platform portal, go to My page > Account management > Authentication key management and click Generate new API authentication key to generate an access key ID and secret key.
  • An existing access key ID and secret key may be used instead.

Request examples

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":"Welcome ${customer_name}. ","body":"Your grade has changed from ${BEFORE_GRADE} to ${AFTER_GRADE}.","recipients":[{"address":"hongildong@naver_.com","name":"Honggildong","type":"R","parameters":{"customer_name":"Honggildong","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"Cheolsu","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

• Generating a signature (use newline character \n)

  • Create a StringToSign according to the request, encrypt via HMAC-SHA256 algorithm by using the SecretKey, and then encode via Base64.
  • This value is used as x-ncp-apigw-signature-v2.

• Sample code

public String makeSignature() {
    String space = " ";  // Space
    String newLine = "\n";  // New line
    String method = "POST";  // HTTP method
    String url = "/api/v1/mails";  // Entire url under "/" except for domain (query string included)
    String timestamp = "{timestamp}";  // Current 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 = " ";  // Space
    $newLine = "\n";  // New line
    $method = "POST";  // HTTP method
    $uri= "/api/v1/mails";  // Entire url under "/" except for domain (query string included)
    $timestamp = "{timestamp}";  // Current 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;
}

Common responses

Returned as HTTP status codes in the response body.

Operation

Sending emails

• createMailRequest
• getMail
• getMailRequestList
• getMailList
• getMailRequestStatus

Managing recipient groups

• createAddressBook
• getAddressBook
• deleteAddressBook
• deleteAddress
• deleteRecipientGroup
• deleteRecipientGroupRelation
• deleteRecipientGroupRelationEmpty

Managing templates

• createCategory
• createTemplate
• createTemplateExportRequest
• deleteCategory
• deleteTemplate
• exportTemplate
• getTemplate
• getTemplateExportRequestList
• getTemplateStructure
• importTemplate
• updateCategory
• updateTemplate
• updateTemplateLocationOrName
• restoreTemplate

Managing project settings

• createConfig
• getConfig

Managing sender blocks and opt-outs

• getSendBlockList
• registerUnsubscribers
• getUnsubscribersList
• deleteUnsubscribers

Managing files

• createFile
• getFile
• deleteFile