Message API reference

Overview

Message Hub provided by Samsung Cloud Platform can send messages through Email, SMS, and Mobile Application Push Notification channels.
This guide provides an explanation of the Message Hub message transmission API and how to invoke it.

Message Hub Call Procedure

The Message Hub API URL must be adjusted based on the operating environment and region, and is categorized as a Public URL or Private URL depending on the call scope. Please check the operating environment and Region information in the table below.

Calling the API

AUTH PARAMS

Header Description

X-Scp-Access-Key   : 삼성 클라우드 플랫폼 포털에서 발급받은 Access Key
X-Scp-Signature    : 호출 API 요청을 Access Key와 매핑되는 Access Secret Key로 암호화한 서명. HMAC 암호화 알고리즘은 HmacSHA256 사용
X-Scp-Timestamp    : 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(Millisecond)로 정의합니다.
X-Scp-Client-Type  : Userapi 고정(대소문자 구분)
Content-Type       : application/json 명시

Create Signature

• To call Message Hub via the message sending API, you must authenticate using the “authentication key” in authentication-key mode from a valid allowed IP address.
• Generate the string to be signed from the request, encrypt it with the HmacSHA256 algorithm using the Access and Secret keys, and then encode it in Base64.
• Use this value as X-Scp-Signature.
• The generated signature is valid for 15 minutes.

Signature generation Sample Code (Java)

public static String makeHmacSignature(String method,
                                       String url,
                                       String timestamp,
                                       String accessKey,
                                       String accessSecretKey,
                                       String clientType) {

    String body = method + url + timestamp + accessKey + clientType;

    String encodeBase64Str;

    try {
        byte[] message = body.getBytes("UTF-8");
        byte[] secretKey = accessSecretKey.getBytes("UTF-8");

        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hmacSha256 = mac.doFinal(message);
        encodeBase64Str = Base64.getEncoder().encodeToString(hmacSha256);
    } catch (Exception e) {
        throw new RuntimeException("Failed to calculate hmac-sha256", e);
    }

    return encodeBase64Str;
}

Signature Generation Sample Code (JavaScript)

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/enc-base64-min.js"></script>
<script type="text/javascript">
function makeSignature() {
    var method = "POST"; // Method
    var url = "{url}"; // url (예: /v1/emails/{email_id}/send)
    var timestamp = Date.now(); // timestamp
    var accessKey = "{accessKey}"; // access key
    var secretKey = "{secretKey}"; // secret key
    var clientType = "Userapi"; // client type

    url = encodeURI(url); // 한글, 특수 문자 처리

    var message = method + url + timestamp + accessKey + clientType;

    var hash = CryptoJS.HmacSHA256(message, secretKey);
    return CryptoJS.enc.Base64.stringify(hash);
}
</script>

Message Hub API call example

Curl

curl -i -X POST
-H "X-Scp-Access-Key:2sd2gg=2agbdSD26svcD"
-H "X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef="
-H "X-Scp-Timestamp:1605290625682"
-H "X-Scp-Client-Type:Userapi"
-H "Content-Type:application/json"
--data '{"recipient_addresses": ["someone@example.com"], "title": "notification title", "body": "notification body"}'
'https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/33ff0000a8a345d78cdf163673f3da11/send'

Python

import requests

url = "https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/33ff0000a8a345d78cdf163673f3da11/send"
payload = {
   'recipient_addresses': ['someone@example.com'],
   'title': 'notification title',
   'body': 'notification body'
}
headers = {
  'X-Scp-Access-Key': '2sd2gg=2agbdSD26svcD',
  'X-Scp-Signature': 'fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=',
  'X-Scp-Timestamp': '1605290625682',
  'X-Scp-Client-Type': 'Userapi',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

if response.status_code == 204:
    return None
else:
    raise Exception(f"Failed to POST API: {response.status_code}, {response.text}")

Java

String apiUrl = "https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/33ff0000a8a345d78cdf163673f3da11/send";
String accessKey = "2sd2gg=2agbdSD26svcD";
String signature = "fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=";
String timestamp = "1605290625682";
String clientType = "Userapi";
String requestBody = "{\"recipient_addresses\":[\"someone@example.com\"],\"title\":\"notification title\",\"body\":\"notification body\"}";

public static void sendMessage(String apiUrl, String requestBody) throws IOException {
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPost postRequest = new HttpPost(apiUrl);
        postRequest.addHeader("X-Scp-Access-Key", accessKey);
        postRequest.addHeader("X-Scp-Signature", signature);
        postRequest.addHeader("X-Scp-Timestamp", timestamp);
        postRequest.addHeader("X-Scp-Client-Type", clientType);
        postRequest.addHeader("Content-Type", "application/json");
        postRequest.setEntity(new StringEntity(requestBody, "UTF-8"));

        HttpResponse response = httpClient.execute(postRequest);
        int statusCode = response.getStatusLine().getStatusCode();

        if (statusCode == 204) {
            httpClient.close();
        } else {
            String responseBody = EntityUtils.toString(response.getEntity());
            httpClient.close();
            throw new RuntimeException("Failed to Request: " + statusCode + ", " + responseBody);
        }
    }

Message Hub Message API

Message Hub provides the following message-sending APIs per channel.

Email sending

POST https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/emails/{email_id}/send

Description

Send an email to the recipient using the registered outbound Email resource.

Path Parameters

Body Parameters

Responses

Errors

Example HTTP request

Request Header

"X-Scp-Access-Key:2sd2gg=2agbdSD26svcD",
"X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=",
"X-Scp-Timestamp:1605290625682",
"X-Scp-Client-Type:Userapi",
"Content-Type:application/json"

Request Body

{
  "recipient_addresses": ["someone@example.com"],
  "title": "notification title",
  "body": "notification body"
}

Example HTTP response

204 Response

Phone Book SMS Sending

POST https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/phones/{phone_id}/send

Description

Send an SMS to the recipient’s phone number using the registered outbound Phone resource.

Path Parameters

Body Parameters

Recipient number input format

Recipient numbers follow the ITU-T E.164 format, and the presence or absence of the + prefix distinguishes domestic and international notation.

Responses

Errors

Example HTTP request

Request Header

"X-Scp-Access-Key:2sd2gg=2agbdSD26svcD",
"X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=",
"X-Scp-Timestamp:1605290625682",
"X-Scp-Client-Type:Userapi",
"Content-Type:application/json"

Request Body

{
  "recipients": ["01012345678", "+14155552671"],
  "text": "sms text"
}

Example HTTP response

204 Response

Push Application Sending

POST https://messagehub.service.kr-west1.e.samsungsdscloud.com/v1/push-applications/{application_id}/send

Description

Send a Push message based on FCM HTTP v1 using the registered Push Application resource and a device token.

Path Parameters

Body Parameters

Responses

Errors

Example HTTP request

Request Header

"X-Scp-Access-Key:2sd2gg=2agbdSD26svcD",
"X-Scp-Signature:fsfsdf235f9U35sdgf35Xsf/qgsdgsdg326=sfsdr23rsef=",
"X-Scp-Timestamp:1605290625682",
"X-Scp-Client-Type:Userapi",
"Content-Type:application/json"

Request Body

{
  "tokens": ["fcm-device-token-1"],
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "priority": "high",
  "ttl": "3600s"
}

Example HTTP response

204 Response