「クラウド型コミュニケーション・プラットフォーム Synergy!」 Synergy! メールAPI
Version 1.0

無料トライアル申し込み

無料トライアルのお申し込みはこちらから。
申込フォームのURL
実際に配信ができるクライアント認証キー、クライアントシークレットを発行いたします。

はじめにお読みください

Synergy! メールAPIは、外部サービスからHTTPS通信を使用して、配信先、配信内容を指定し、メールを配信する事ができるAPIです。
RESTを適用しており、必要なパラメータを指定してURLにアクセスしますと、その結果を取得することができます。

リクエストURL

配信 配信設定 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries POST 配信内容(差出人・本文・宛先リスト等)を設定し、配信を開始します
https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID} GET 配信状態を取得します
https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID} DELETE 配信設定を削除します
https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/new POST 配信内容(差出人・本文・宛先リスト等)を設定し、配信IDを発行します
https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/send POST 指定の配信IDの配信内容で配信を開始します
予約配信設定 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/reserve/sendlists POST 予約配信用の配信先リストを登録します
https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/reserve/sendlists/{配信先リストID} GET 配信先リスト情報を取得します
https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/reserve POST 配信の予約を行います
配信結果 開封確認結果取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/opens GET メールが開封された宛先を取得します
クリックフィードバック結果取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/clicks GET メール内のURLがクリックされた宛先を取得します
配信エラー結果取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/errors GET 配信が失敗した宛先を取得します
配信結果取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/results GET 配信結果を取得します
配信解除依頼リスト取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/unsubscribes GET 配信解除依頼をした宛先を取得します
全配信エラー結果取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/errors/all GET 全ての配信から配信が失敗した宛先を取得します
全配信解除依頼リスト取得 https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/unsubscribes/all GET 全ての配信から配信解除依頼をした宛先を取得します

補足事項

SSL通信(TLS1.2またはTLS1.3)が必要となります。
各APIに応じて適切なメソッド(GET,POST)でリクエストする必要があります。
APIの通信時の文字コードはUTF-8、エンコーディング形式はBase64エンコード+パーセントエンコーディング(URLエンコード)です。
ユーザ名はご契約時にお知らせする3~4文字のアルファベット文字列です。
Synergy!認証APIへのリクエストに必要なクライアントシークレットの再発行が必要な場合は、弊社Synergy!カスタマーサポートまでご相談ください。


認証

認証方法

Synergy! メールAPIにアクセスするためには、リクエストヘッダにアクセストークンを付与する必要があります。
アクセストークンは事前にSynergy!認可サーバから OAuth 2.0 のクライアント・クレデンシャルズフローにより取得します。

シーケンス図

クライアント・クレデンシャルズフローはRFC 6749, 4.4. Client Credentials Grant で定義されているフローです。
Synergy!認可サーバにトークン取得のリクエストを送り、レスポンスとしてアクセストークンを受け取るフローです。
以下、Synergy! メールAPIにアクセスする際の流れを表した図です。

メールAPIアクセスの流れ

アクセストークン取得

Synergy! メールAPIにアクセスするためのアクセストークンを取得します。

リクエストURL

URL https://auth.paas.crmstyle.com/oauth2/token
メソッド POST

リクエストヘッダ

フィールド名 内容
Authorization Basic {クライアントクレデンシャルズ}
※クライアントクレデンシャルズは、事前に発行したクライアント認証キー, クライアントシークレットを:(コロン)で繋いで、base64でエンコードした文字列を指定します。
Content-Type application/x-www-form-urlencoded

リクエストパラメータ

プロパティ名 説明
grant_type String OAuth 2.0の処理フローを表します。
"client_credentials" を指定してください。
audience String アクセスするAPIのドメインを表します。
"https://mail.paas.crmstyle.com" を指定してください。
scope String アクセスするAPIの種別を表します。
指定できるscopeはこちらを参照してください。
複数指定する場合は半角スペースをscopeの間に含めて指定してください。

scope一覧

scope名 アクセスできるAPI
mail:send
mail:result

リクエストサンプル

CLIENT_ID={your client id}
CLIENT_SECRET={your client secret}
AUTH_HEADER=`echo -n ${CLIENT_ID}:${CLIENT_SECRET} | base64`
curl -i -X POST \
     -H "Authorization: Basic ${AUTH_HEADER}" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     https://auth.paas.crmstyle.com/oauth2/token \
     -d "grant_type=client_credentials&scope=mail:send mail:result&audience=https://mail.paas.crmstyle.com"

レスポンス

レスポンスはJSON形式で返します。

レスポンスサンプル

{
  "access_token": "{Access Token}",
  "expires_in": 3599,
  "scope": "mail:send mail:result",
  "token_type": "bearer"
}

レスポンスJSONプロパティ

プロパティ名 説明
access_token String Synergy! メールAPI にアクセスするためのアクセストークンです。
expires_in Integer アクセストークンの有効期限が切れるまでの秒数を表します。
scope String アクセストークンに含まれるscopeの一覧を表します。
token_type String トークンの種別を表します。
bearer固定です。

Synergy! メールAPIリクエスト

メールAPIリクエストの際、Authorization ヘッダにアクセストークンを指定してください。

リクエスト例(開封確認結果取得)

ACCESS_TOKEN={your acccess token}
curl -i \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     https://mail.paas.crmstyle.com/e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/opens

補足事項

アクセストークンには1時間の有効期限があります。
有効期限切れとなった場合は、再度アクセストークンを取得してください。
有効期限切れのアクセストークンを指定されてメールAPIをリクエストされた場合、401 Unauthorized エラーを返します。

また、Synergy! メールAPI へアクセスするたびにアクセストークンを取得しないようにしてください。
アクセストークンを取得するAPIには、IPアドレス単位で1分間あたり最大100リクエストの上限が設けられています。
上限を超えてリクエストされた場合、429 Too Many Requests エラーを返します。
429エラーになった場合は、1分程度時間をあけてから再度アクセスしてください。


API仕様

配信

メール配信実施
POST /e/tymail/v1/{ユーザ名}/mail/deliveries

メールコンテンツ、配信先リストを指定して配信を開始します。

リクエストサンプル

{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "test": false,
  "encode": "UTF-8",
  "fromAddress": "support@example.com",
  "fromName": "カスタマーサポート",
  "replyAddress": "reply@example.com",
  "subject": "こんにちは($db.Customer.name$)さん",
  "bodyText": "お問い合わせは次のURLから http://example.com/",
  "bodyHtml": "<html><head></head><body>
お問い合わせは次のURLから<a href=\"http://example.com/\" symccid=\"0\" symcc=\"true\">フォーム</a>
</body></html>",
  "deliveryMailAddressPropertyName": "Customer.mailaddress",
  "count": 2,
  "deliveryData": [
    {
      "Customer.synergyid":         1,
      "Customer.mailaddress":      "foo@example.com",
      "Customer.name":                "山田"
    },
    {
      "Customer.synergyid":         2,
      "Customer.mailaddress":      "bar@example.com",
      "Customer.name":                "佐藤"
    }
  ],
  "oneClickUnsubscriptionReady": true
}

JSONプロパティ

プロパティ名 必須 デフォルト値 説明
requestId String API多重リクエストによる重複配信防止用のIDです。
指定のIDで既に配信が設定されている場合、リクエストエラーとなり配信されません。その際、レスポンスは以前の配信設定と同一となります。
requestIdには有効期間があり、1ヵ月です。期間を過ぎて以前のrequestIdを指定した場合は配信が実施されます。
指定されない場合は常に配信が実施されます。
IDはUUIDを推奨します。
test Boolean false テスト配信指定フラグです。trueの場合はテスト配信となり、各種レポートが記録されません。
テスト配信では配信IDが発行されないため、レスポンスは空値となります。
テスト配信では配信通数は20通までとなります。
encode String UTF-8 メールのエンコーディングをUTF-8、ISO-2022-JPのどちらか指定します。
fromAddress String メール差出人アドレスを指定します。
fromName String メール差出人名を指定します。
replyAddress String メール返信先アドレスを指定します。
preheader String プレヘッダ―を指定します。
subject String メール件名を指定します。
bodyText String メールテキスト本文を指定します。
bodyText、bodyHtmlどちらかは必須です。
本文のサイズは512KBまでです。
bodyHtml String メールHTML本文を指定します。
bodyText、bodyHtmlどちらかは必須です。
本文のサイズは512KBまでです。
deliveryMailAddressPropertyName String 配信先リスト(deliveryData[])中の宛先メールアドレスのプロパティ名を指定します。
trackingDomain String クリックフィードバックURLに独自ドメインを使用する場合にドメインを指定します。
※独自ドメインのご利用は別途お申し込みが必要です。
trackingDomainSslReady Boolean false クリックフィードバックURLに使用する独自ドメインがSSL通信可能かどうかを指定します。
count Integer 配信先リスト(deliveryData[])の長さを指定します。
配信先リスト長がcountと一致しない場合、リクエストエラーとなり配信されません。
deliveryData[] Array 配信先リストです。宛先データをハッシュ配列で指定します。
プロパティCustomer.synergyidはレポートデータ紐づけのIDとなり、必須です。型はIntegerです。1以上2^63-1(9,223,372,036,854,775,807)以下の範囲で指定します。
宛先メールアドレスとなる文字列プロパティが必須です。プロパティ名は任意で、deliveryMailAddressPropertyNameで指定します。
埋め込みコマンドとして任意の文字列データを指定可能です。
配信先リスト内のプロパティ名については、以下の制限があります。
・プロパティ名がCustomer.で始まること
・Customer.の次の文字はアルファベットかアンダーバー、それ以降は英数字かアンダーバーで構成されていること
・全体で63文字以内であること
配列長はcountプロパティと一致しなければなりません。
oneClickUnsubscriptionReady Boolean false メール受信者より配信解除依頼を受け付けるかどうかを指定します。
trueを指定することで、List-UnsubscribeヘッダとList-Unsubscribe-Postヘッダが追加されます。
・追加されるメールヘッダの例
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://(解除用URL)>

Gmailアプリなどの対応メーラーでこのメールを受信した際、受信者がメーラー側に表示される解除リンクから配信解除を依頼できます。
メール配信後は、配信解除依頼リストAPIで解除希望者を取得し、次回以降の配信先リストから除外してください。

レスポンスサンプル

{
  "deliveryTaskId":9999,
  "textClickFeedbacks":[{"id": 14,"url": "http://example.com/"}],
  "htmlClickFeedbacks":[{"id": 15,"url": "http://example.com/"}]
}

JSONプロパティ

プロパティ名 説明
deliveryTaskId Integer メール配信IDです。配信状況、各種レポート取得時に必要となります。
textClickFeedbacks Array bodyText中から発行されたクリックフィードバックの一覧です。
textClickFeedbacks.id Integer クリックフィードバックIDです。
textClickFeedbacks.url String クリックフィードバック変換前のURLです。
htmlClickFeedbacks Array bodyHtml中から発行されたクリックフィードバックの一覧です。
htmlClickFeedbacks.id Integer クリックフィードバックIDです。
htmlClickFeedbacks.url String クリックフィードバック変換前のURLです。

配信状態取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}

指定の配信IDの配信状態を取得します。

レスポンスサンプル

{
  "deliveryTaskId": 9999,
  "status": "SENDING",
  "total": 58933,
  "sent": 45000
}

JSONプロパティ

プロパティ名 説明
deliveryTaskId Integer メール配信IDです。
status String 配信の状態をSENDING,COMPLETED,RESERVED,ERRORのいずれかで表します。
SENDING: 配信処理中です。 {sent} 通まで配信処理が完了しています。
COMPLETED: 配信を完了しています。{sent} {total} が一致します。{sent} {total} がともに0の場合もCOMPLETEDが返されます。
RESERVED: 予約中です。
ERROR: エンジニア対応により強制終了された状態です。※通常発生しません。
total Integer 配信総数です。
sent Integer 配信完了数です。

配信設定削除
DELETE /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}

指定の配信IDの配信設定を削除します。削除すると各種配信結果は取得できません。
配信予約中の配信設定を削除した場合、配信先リストとの紐付けが解除され、対象の配信先リストに別の配信設定を紐付けられるようになります。
また、配信予約中の配信設定で、現在日時が配信予約日時の5分前より後の場合、配信が完了するまで削除できません。

メール配信設定作成
POST /e/tymail/v1/{ユーザ名}/mail/deliveries/new

メールコンテンツを指定して配信設定を作成します。

リクエストサンプル

{
  "encode": "UTF-8",
  "fromAddress": "support@example.com",
  "fromName": "カスタマーサポート",
  "replyAddress": "reply@example.com",
  "subject": "こんにちは($db.Customer.name$)さん",
  "bodyText": "お問い合わせは次のURLから http://example.com/",
  "bodyHtml": "<html><head></head><body>
お問い合わせは次のURLから<a href=\"http://example.com/\" symccid=\"0\" symcc=\"true\">フォーム</a>
</body></html>",
  "deliveryMailAddressPropertyName": "Customer.mailaddress"
}

JSONプロパティ

プロパティ名 必須 デフォルト値 説明
encode String UTF-8 メールのエンコーディングをUTF-8、ISO-2022-JPのどちらか指定します。
fromAddress String メール差出人アドレスを指定します。
fromName String メール差出人名を指定します。
replyAddress String メール返信先アドレスを指定します。
preheader String プレヘッダ―を指定します。
subject String メール件名を指定します。
bodyText String メールテキスト本文を指定します。
bodyText、bodyHtmlどちらかは必須です。
本文のサイズは512KBまでです。
bodyHtml String メールHTML本文を指定します。
bodyText、bodyHtmlどちらかは必須です。
本文のサイズは512KBまでです。
deliveryMailAddressPropertyName String 配信実施時の配信先リスト(deliveryData[])中の宛先メールアドレスのプロパティ名を指定します。

レスポンスサンプル

{
  "deliveryTaskId":9999,
  "textClickFeedbacks":[{"id": 14,"url": "http://example.com/"}],
  "htmlClickFeedbacks":[{"id": 15,"url": "http://example.com/"}]
}

JSONプロパティ

プロパティ名 説明
deliveryTaskId Integer メール配信IDです。配信状況、各種レポート取得時に必要となります。
textClickFeedbacks Array bodyText中から発行されたクリックフィードバックの一覧です。
textClickFeedbacks.id Integer クリックフィードバックIDです。
textClickFeedbacks.url String クリックフィードバック変換前のURLです。
htmlClickFeedbacks Array bodyHtml中から発行されたクリックフィードバックの一覧です。
htmlClickFeedbacks.id Integer クリックフィードバックIDです。
htmlClickFeedbacks.url String クリックフィードバック変換前のURLです。

指定の配信IDのメール配信実施
POST /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/send

指定の配信IDの配信設定を利用し、配信先リストを指定して配信を開始します。
指定した配信IDの配信設定が配信予約されているものは利用できません。

リクエストサンプル

{
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "test": false,
  "count": 2,
  "deliveryData": [
    {
      "Customer.synergyid":         1,
      "Customer.mailaddress":      "foo@example.com",
      "Customer.name":                "山田"
    },
    {
      "Customer.synergyid":         2,
      "Customer.mailaddress":      "bar@example.com",
      "Customer.name":                "佐藤"
    }
  ],
  "oneClickUnsubscriptionReady": true
}

JSONプロパティ

プロパティ名 必須 デフォルト値 説明
requestId String API多重リクエストによる重複配信防止用のIDです。
指定のIDで既に配信が設定されている場合、リクエストエラーとなり配信されません。
requestIdには有効期間があり、1ヵ月です。期間を過ぎて以前のrequestIdを指定した場合は配信が実施されます。
指定されない場合は常に配信が実施されます。
IDはUUIDを推奨します。
test Boolean false テスト配信指定フラグです。trueの場合はテスト配信となり、各種レポートが記録されません。
テスト配信では配信IDが発行されないため、レスポンスは空値となります。
テスト配信では配信通数は20通までとなります。
trackingDomain String クリックフィードバックURLに独自ドメインを使用する場合にドメインを指定します。
※独自ドメインのご利用は別途お申し込みが必要です。
trackingDomainSslReady Boolean false クリックフィードバックURLに使用する独自ドメインがSSL通信可能かどうかを指定します。
count Integer 配信先リスト(deliveryData[])の長さを指定します。
配信先リスト長がcountと一致しない場合、リクエストエラーとなり配信されません。
deliveryData[] Array 配信先リストです。宛先データをハッシュ配列で指定します。
プロパティCustomer.synergyidはレポートデータ紐づけのIDとなり、必須です。型はIntegerです。1以上2^63-1(9,223,372,036,854,775,807)以下の範囲で指定します。
宛先メールアドレスとなる文字列プロパティが必須です。プロパティ名はメール配信設定作成APIで指定したプロパティ名でなければなりません。
埋め込みコマンドとして任意の文字列データを指定可能です。
配信先リスト内のプロパティ名については、以下の制限があります。
・プロパティ名がCustomer.で始まること
・Customer.の次の文字はアルファベットかアンダーバー、それ以降は英数字かアンダーバーで構成されていること
・全体で63文字以内であること
配列長はcountプロパティと一致しなければなりません。
oneClickUnsubscriptionReady Boolean false メール受信者より配信解除依頼を受け付けるかどうかを指定します。
trueを指定することで、List-UnsubscribeヘッダとList-Unsubscribe-Postヘッダが追加されます。
・追加されるメールヘッダの例
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://(解除用URL)>

Gmailアプリなどの対応メーラーでこのメールを受信した際、受信者がメーラー側に表示される解除リンクから配信解除を依頼できます。
メール配信後は、配信解除依頼リストAPIで解除希望者を取得し、次回以降の配信先リストから除外してください。

レスポンスサンプル

{
  "deliveryTaskId":9999,
  "textClickFeedbacks":[{"id": 14,"url": "http://example.com/"}],
  "htmlClickFeedbacks":[{"id": 15,"url": "http://example.com/"}]
}

JSONプロパティ

プロパティ名 説明
deliveryTaskId Integer メール配信IDです。配信状況、各種レポート取得時に必要となります。
textClickFeedbacks Array bodyText中から発行されたクリックフィードバックの一覧です。
textClickFeedbacks.id Integer クリックフィードバックIDです。
textClickFeedbacks.url String クリックフィードバック変換前のURLです。
htmlClickFeedbacks Array bodyHtml中から発行されたクリックフィードバックの一覧です。
htmlClickFeedbacks.id Integer クリックフィードバックIDです。
htmlClickFeedbacks.url String クリックフィードバック変換前のURLです。

予約配信用の配信先リストの登録
POST /e/tymail/v1/{ユーザ名}/mail/deliveries/reserve/sendlists

予約配信用の配信先リストをCSV形式で登録します。
Content-Typeヘッダにはtext/csvを指定し、リクエストボディにCSVデータをセットします。リクエストボディのサイズ上限は300MBです。
文字コードはUTF-8エンコーディングとして扱います。

CSVデータの内容には以下の制約があり、満たされていない場合配信先リストの登録に失敗します。
・レポートデータ紐付けのIDとしてヘッダにCustomer.synergyidカラムおよび各行にその値が必須です。値は1以上2^63-1(9,223,372,036,854,775,807)以下の範囲で指定します。
・Customer.synergyidに加え、宛先メールアドレスとなるカラムが必須です。予約配信リクエストのdeliveryMailAddressPropertyNameで指定します。
・埋め込みコマンドとして任意の文字列データを設定可能です。カラム名には以下の制約があり、満たされていない場合、配信先リストの登録に失敗します。
 ・カラム名がCustomer.で始まること
 ・Customer.の次の文字はアルファベットかアンダーバー、それ以降は英数字かアンダーバーで構成されていること
 ・全体で63文字以内であること
・ヘッダのカラム名は重複のない名前を指定してください。
・ヘッダのカラムの数と各行の値の数は一致させてください。
・埋め込みコマンドとして使用する文字列データは4000文字を上限とします。

配信先リストが正常に登録できたかどうかは、配信先リスト情報取得APIで確認できます。

リクエストサンプル

"Customer.synergyid","Customer.mailaddress","Customer.name"
"1","foo@example.com","山田"
"2","bar@example.com","佐藤"

レスポンスサンプル

{
  "sendListId":9999
}

JSONプロパティ

プロパティ名 説明
sendListId Integer 配信先リストIDです。配信予約時にリクエストに指定します。

配信先リスト情報取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/reserve/sendlists/{配信先リストID}

指定の配信先リストIDの情報を取得します。

レスポンスサンプル

{
  "sendListId":9999,
  "status": "SUCCESS",
  "expirationDateTime": "2016-09-12T08:21:38+09:00",
  "rowCount": 12345,
  "errorMessage": null,
  "deliveryTaskId":9999
}

JSONプロパティ

プロパティ名 説明
sendListId Integer 配信先リストIDです。
status String 配信先リスト登録状況をSUCCESS,FAIL,PROCESSING,EXPIREDのいずれかで表します。
SUCCESS: 配信先リストが正常に登録されました。
FAIL: 配信先リスト登録が失敗しました。詳細は {errorMessage} をご確認ください。
PROCESSING: 配信先リストを登録中です。
EXPIRED: 配信先リストが有効期限切れです。
expirationDateTime DateTime 配信先リストの有効期限です。
rowCount Integer ヘッダ行を除く配信先リストの総行数です。
errorMessage String 配信先リスト登録に失敗した場合、失敗した理由が記載されます。メッセージが存在しない場合はnullになります。
deliveryTaskId Integer 指定した配信先リストを使用している配信設定IDです。使用している配信設定が存在しない場合はnullになります。

配信予約
POST /e/tymail/v1/{ユーザ名}/mail/deliveries/reserve

指定の配信IDに紐付いた配信先リストをもとに、配信予約を行います。

リクエストサンプル

{
  "sendListId": 9999,
  "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "encode": "UTF-8",
  "fromAddress": "support@example.com",
  "fromName": "カスタマーサポート",
  "replyAddress": "reply@example.com",
  "subject": "こんにちは($db.Customer.name$)さん",
  "bodyText": "お問い合わせは次のURLから http://example.com/",
  "bodyHtml": "<html><head></head><body>
お問い合わせは次のURLから<a href=\"http://example.com/\" symccid=\"0\" symcc=\"true\">フォーム</a>
</body></html>",
  "deliveryMailAddressPropertyName": "Customer.mailaddress",
  "sendDateTime": "2016-09-12T08:21:38+09:00",
  "oneClickUnsubscriptionReady": true
}

JSONプロパティ

プロパティ名 必須 デフォルト値 説明
sendListId Integer 配信で使用する配信先リストのIDを指定します。
同じ配信先リストIDに対して複数個配信設定を紐付けることはできません。
requestId String API多重リクエストによる重複配信防止用のIDです。
指定のIDで既に配信が設定されている場合、リクエストエラーとなり配信されません。
requestIdには有効期間があり、1ヵ月です。期間を過ぎて以前のrequestIdを指定した場合は配信が実施されます。
指定されない場合は常に配信が実施されます。
IDはUUIDを推奨します。
encode String UTF-8 メールのエンコーディングをUTF-8、ISO-2022-JPのどちらか指定します。
fromAddress String メール差出人アドレスを指定します。
fromName String メール差出人名を指定します。
replyAddress String メール返信先アドレスを指定します。
preheader String プレヘッダ―を指定します。
subject String メール件名を指定します。
bodyText String メールテキスト本文を指定します。
bodyText、bodyHtmlどちらかは必須です。
本文のサイズは512KBまでです。
bodyHtml String メールHTML本文を指定します。
bodyText、bodyHtmlどちらかは必須です。
本文のサイズは512KBまでです。
deliveryMailAddressPropertyName String 配信先リスト中の宛先メールアドレスのプロパティ名を指定します。
trackingDomain String クリックフィードバックURLに独自ドメインを使用する場合にドメインを指定します。
※独自ドメインのご利用は別途お申し込みが必要です。
trackingDomainSslReady Boolean false クリックフィードバックURLに使用する独自ドメインがSSL通信可能かどうかを指定します。
sendDateTime DateTime 配信予約日時をISO 8601フォーマットで指定します。
(例)2019-04-01T15:00:00+09:00
指定可能な日時は、現在時刻の5分後から、指定した配信先リストを登録した日時の7日後までです。
予約日時は、配信処理の開始の目安とし、最大5分程度の遅延が生じる可能性があります。
oneClickUnsubscriptionReady Boolean false メール受信者より配信解除依頼を受け付けるかどうかを指定します。
trueを指定することで、List-UnsubscribeヘッダとList-Unsubscribe-Postヘッダが追加されます。
・追加されるメールヘッダの例
List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-Unsubscribe: <https://(解除用URL)>

Gmailアプリなどの対応メーラーでこのメールを受信した際、受信者がメーラー側に表示される解除リンクから配信解除を依頼できます。
メール配信後は、配信解除依頼リストAPIで解除希望者を取得し、次回以降の配信先リストから除外してください。

レスポンスサンプル

{
  "deliveryTaskId":9999,
  "textClickFeedbacks":[{"id": 14,"url": "http://example.com/"}],
  "htmlClickFeedbacks":[{"id": 15,"url": "http://example.com/"}]
}

JSONプロパティ

プロパティ名 説明
deliveryTaskId Integer メール配信IDです。配信状況、各種レポート取得時に必要となります。
textClickFeedbacks Array bodyText中から発行されたクリックフィードバックの一覧です。
textClickFeedbacks.id Integer クリックフィードバックIDです。
textClickFeedbacks.url String クリックフィードバック変換前のURLです。
htmlClickFeedbacks Array bodyHtml中から発行されたクリックフィードバックの一覧です。
htmlClickFeedbacks.id Integer クリックフィードバックIDです。
htmlClickFeedbacks.url String クリックフィードバック変換前のURLです。

配信結果

各配信結果APIのレスポンスでは、レスポンスCSVデータのMD5チェックサム値がレスポンスヘッダContent-MD5に設定されます。
一時的なネットワーク接続性の問題が発生した場合、正常にCSVデータを受信できない可能性がありますので、
MD5チェックサムによるCSVデータの整合性確認を必ず行ってください。
正常なCSVデータのMD5チェックサム値は、レスポンスヘッダContent-MD5に、チェックサム値をBase64エンコーディングしたものが設定されます。

Content-Typeヘッダは application/octet-stream;charset=UTF-8 となります。

各配信結果APIでは、クエリパラメータ start/end で取得期間の指定が可能です。
取得期間の指定は、開始終了・開始のみ・終了のみの指定が可能です。
両方ともに指定しない場合、全期間が対象となります。全配信エラー結果取得API・全配信解除依頼リスト取得APIのみ、取得可能な期間は現在日時から6ヶ月前の1日以降です。
日時指定フォーマットはISO 8601です。

クエリパラメータ

パラメータ名 必須 デフォルト値 説明
start DateTime 取得期間(開始)をISO 8601フォーマットで指定します。
end DateTime 取得期間(終了)をISO 8601フォーマットで指定します。

期間指定例

2019年4月1日のデータを取得 start=2019-04-01T00:00:00+09:00&end=2019-04-02T00:00:00+09:00
2019年4月1日以降のデータを取得 start=2019-04-01T00:00:00+09:00
2019年3月31日までのデータを取得 end=2019-04-01T00:00:00+09:00
2019年4月1日15時台のデータを取得 start=2019-04-01T15:00:00+09:00&end=2019-04-01T16:00:00+09:00

※「+」は「%2B」に URLエンコードしてください。
 (例)start=2019-04-01T15:00:00%2B09:00

開封確認結果取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/opens

指定のメール配信の開封確認結果(CSV)を取得します。

レスポンスサンプル

"Synergy!ID","開封日時"
"493","2016-09-12 08:21:38"

クリックフィードバック結果取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/clicks

指定のメール配信のクリックフィードバック結果(CSV)を取得します。

レスポンスサンプル

"Synergy!ID","クリック日時","クリックID","クリックURL"
"493","2016-09-12 08:21:38","123","http//example.com/"

配信エラー結果取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/errors

指定のメール配信の配信エラー結果(CSV)を取得します。

レスポンスサンプル

"Synergy!ID","配信エラー日時","配信エラー理由"
"493","2016-09-12 08:21:38","UNKNOWN_USER"

配信エラー理由一覧

エラーコード 説明
UNKNOWN_USER 宛先不明
UNKNOWN_HOST ドメインが見つからない
MAILBOX_FULL メールボックスが一杯
REJECTED 受信拒否
SPAM SPAMと見なされた
INVALID_ADDRESS メールアドレス書式エラー
SYSTEM 配信リストクリーニング機能による除外
OTHER その他エラー

配信結果取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/results

指定のメール配信の結果(CSV)を取得します。

※反映されるには配信から通常、1分ほどかかります。

レスポンスサンプル

"Synergy!ID","配信日時"
"10038","2020-04-28 16:20:09"

配信解除依頼リスト取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/{配信ID}/unsubscribes

指定のメール配信の配信解除依頼リスト(CSV)を取得します。
受信者が購読解除を依頼していますので、次回以降の配信では配信先リストから除外し、配信対象とならないようにしてください。

レスポンスサンプル

"Synergy!ID","配信解除依頼日時"
"30114","2023-09-12 12:34:56"

全配信エラー結果取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/errors/all

全配信の配信エラー結果(CSV)を取得します。
取得可能な期間は現在日時から6ヶ月前の1日以降です。それより前のデータは取得できません。
startにそれより前の日時を指定した場合も6ヶ月前の1日から現在日時までのデータのみ取得可能です。
(例)現在日時が2023/09/12 01:23:45の場合、2023/03/01 00:00:00から2023/09/12 01:23:45までのデータが取得可能
配信エラー理由の内容は配信エラー結果取得の配信エラー理由一覧と同様です。

レスポンスサンプル

"Synergy!ID","配信エラー日時","配信エラー理由","配信ID"
"20076","2023-09-12 12:34:56","UNKNOWN_USER","9999"

全配信解除依頼リスト取得
GET /e/tymail/v1/{ユーザ名}/mail/deliveries/unsubscribes/all

全配信の配信解除依頼リスト(CSV)を取得します。
受信者が購読解除を依頼していますので、次回以降の配信では配信先リストから除外し、配信対象とならないようにしてください。
取得可能な期間は現在日時から6ヶ月前の1日以降です。それより前のデータは取得できません。
startにそれより前の日時を指定した場合も6ヶ月前の1日から現在日時までのデータのみ取得可能です。
(例)現在日時が2023/09/12 01:23:45の場合、2023/03/01 00:00:00から2023/09/12 01:23:45までのデータが取得可能

レスポンスサンプル

"Synergy!ID","配信解除依頼日時","配信ID"
"30114","2023-09-12 12:34:56","9999"

エラーコード

Synergy! メールAPIから返されるエラー定義

HTTPステータスコードを使います。

ステータス
コード
説明 備考
200 OK 成功
400 Bad Request 要求されたリクエストパラメータの形式が正しくない
※レスポンスボディにエラー情報を返します
401 Unauthorized 認証が正しくない、または認証データが見つからない
403 Forbidden リソースにアクセスする権限が不足している
404 Not Found 不正なURLリクエストが送信された、またはリソースが見つからない(ユーザが見つからないなど)
405 Method Not Allowed リクエストで指定されたメソッドが見つからない
409 Conflict 指定されたrequestIdのリクエストが以前のリクエストと重複
429 Too Many Requests 一定時間内に送信したリクエスト数が多すぎる
500 Internal Server Error サーバ内部でエラーが発生
503 Service Unavailable サーバメンテナンス中もしくはなんらかの障害が発生

ステータスコード400のエラーについては、エラーメッセージも返します。

レスポンスサンプル

{
  "errors":[
    {
      "code": 10000,
      "property": "fromAddress",
      "message": "required"
    },
    {
      "code": 10001,
      "property": "subject",
      "message": "required"
    },
    {
      "code": 10002,
      "property": null,
      "message": "bodyText or bodyHtml is required"
    }
  ]
}

JSONプロパティ

プロパティ名 説明
errors[] Array 発生したエラー内容のハッシュ配列です
errors[].code String 発生したエラーのエラーコードです。
errors[].property String 発生したエラーの原因となったリクエストデータのプロパティ名です。
特定のプロパティが原因でない場合、nullです。
errors[].message String 発生したエラーの説明です。

エラーコード一覧

エラーコード プロパティ エラー原因 関連API
10000 encode エンコードはUTF-8もしくはISO-2022-JPである必要があります メール配信実施
10002 trackingDomain お申し込みいただいていないドメインです メール配信実施
10003 fromAddress 差出人アドレスは必須です。 メール配信実施
10004 fromAddress メールアドレス書式が不正です。 メール配信実施
10005 fromAddress メールアドレスは256文字以下である必要があります。 メール配信実施
10006 fromName 差出人名は120文字以下である必要があります。 メール配信実施
10007 replyAddress メールアドレス書式が不正です。 メール配信実施
10008 replyAddress メールアドレスは256文字以下である必要があります。 メール配信実施
10009 subject 件名は必須です。 メール配信実施
10010 subject 件名は120文字以下である必要があります。 メール配信実施
10011 bodyText/bodyHtml テキスト本文かHTML本文のどちらかは必須です。 メール配信実施
10012 count 配信リスト長は必須です。 メール配信実施
10013 count deliveryDataのサイズが配信リスト長と一致しません。 メール配信実施
10014 count テスト配信は最大20通です。 メール配信実施
10015 deliveryMailAddressPropertyName 宛先メールアドレスのプロパティ名は必須です。 メール配信実施
10016 deliveryData 配信リストは必須です。 メール配信実施
10017 deliveryData 配信リスト中に Customer.synergyid は必須です。 メール配信実施
10018 deliveryData 配信リスト中の Customer.synergyid は1以上2^63-1(9,223,372,036,854,775,807)以下の範囲の数値である必要があります。 メール配信実施
10019 deliveryData 配信リスト中にdeliveryMailAddressPropertyNameで指定されたメールアドレス項目が必須です。 メール配信実施
10020 start end 日時指定フォーマットが不正です。ISO 8601フォーマットで指定してください。 配信結果
10021 deliveryTaskId 配信処理中は削除できません。 配信設定削除
10022 sendListId 配信先リストIDは必須です。 配信予約
10023 sendListId 指定した配信先リストIDに該当する配信先リストが存在しません。 配信予約
10024 sendListId 指定した配信先リストIDに該当する配信先リストは有効期限切れのため利用できません。 配信予約
10025 sendListId 指定した配信先リストIDに該当する配信先リストは正常に登録が完了していないため利用できません。 配信予約
10026 sendListId 指定した配信先リストIDに該当する配信先リストはすでに別の配信に利用されています。 配信予約
10027 deliveryMailAddressPropertyName 登録した配信先リストの中にdeliveryMailAddressPropertyNameで指定したメールアドレス項目がありません。 配信予約
10028 sendDateTime 配信予約日時は必須です。 配信予約
10029 sendDateTime 日時指定フォーマットが不正です。ISO 8601フォーマットで指定してください。 配信予約
10030 sendDateTime 配信予約日時の値が不正です。現在時刻の5分後から配信先リストの有効期限の範囲で指定してください。 配信予約
10031 deliveryTaskId 現在日時が配信予約日時の5分前より後の場合、配信が完了するまで削除できません。 配信設定削除
10032 bodyText/bodyHtml 本文のサイズは512KBまでです。 メール配信実施
10033 deliveryTaskId 指定した配信IDの配信設定は配信予約されており、即時配信には利用できません。 メール配信実施
10034 リクエストボディに指定したJSONは型の不整合やフォーマットの問題があります。 メール配信実施
10035 deliveryData 配信リスト中のプロパティ名が指定している形式に違反しています。 メール配信実施

その他

埋め込みコマンドを使用する

埋め込みコマンドは配信先リストのハッシュキーをメール本文中に"($db.Customer.name$)"のように含めることで、個々のデータをメールに記載することができます。
埋め込みコマンドは以下の箇所で使用できます。
 ・メール差出人アドレス
 ・メール差出人名
 ・メール返信先アドレス
 ・メール件名
 ・メールテキスト本文
 ・メールHTML本文
※メール差出人名、差出人アドレスに埋め込みコマンドを使用することで、私信風メールを送ることができます。

・配信先リスト例(JSON)

  "deliveryData": [
    {
      "Customer.synergyid":        1,
      "Customer.mailaddress":      "foo@example.com",
      "Customer.name":             "山田",
      "Customer.created_at":       "2019/03/01",
      "Customer.point":            99
    }
  ]

・配信先リスト例(CSV)

Customer.synergyid,Customer.mailaddress,Customer.name,Customer.created_at,Customer.point
1,foo@example.com,山田,2019/03/01,99

・本文テキスト設定例

($db.Customer.name$) 様

あなたの登録日は($db.Customer.created_at$)で、残ポイントは($db.Customer.point$)です。

・実際に届くメール

山田 様

あなたの登録日は2019/03/01で、残ポイントは99です。

・注意事項
埋め込みコマンドとして利用するプロパティは、配信リスト(deliveryData[])の先頭のハッシュに含まれるプロパティで決定されます。
2列目以降に先頭のハッシュに含まれないプロパティが含まれる場合、埋め込みコマンドのデータとして認識されません。


テキストメール、HTMLメールを送る

配信設定等で本文を指定する際、指定の仕方によって配信したいメール形式をわけることができます。

メール形式 指定する本文
テキストメール 本文テキストのみ
HTMLメール 本文HTMLのみ
マルチパートメール 本文テキストと本文HTMLの両方

クリックフィードバックを使用する

クリックフィードバックはメール本文に所定の書式でURLを含めることで、メール受信者のURLへのアクセスを記録することができます。
テキスト本文、HTML本文で書式が異なり、それぞれ以下の通りです。

書式 書式サンプル 受信サンプル
テキスト本文 <sym-tr symccid="0" symcc="true">{URL}</sym-tr> <sym-tr symccid="0" symcc="true">http://example.com/</sym-tr> http://us.msgs.jp/XXXXXXXXXXXXXX
HTML本文 <a symccid="0" symcc="true" href="{URL}">{任意の文字列}</a> <a symccid="0" symcc="true" href="http://example.com/">応募サイト</a> <a href="http://us.msgs.jp/XXXXXXXXXXXXXX">応募サイト</a>

APIコール数、通数制限について

APIコール数は最大で秒間5コールを目安とし、それを超える場合429のステータスコードを返すことがあります。
1コールあたりの通数に制限はありませんが、100万通程度を推奨します。
それ以上を配信される場合は、配信先リスト登録による予約配信をご検討ください。

Synergy! メールAPIは、APIコール数、通数制限の範囲内にてご利用ください。
利用制限に反する利用等、弊社がSynergy! メールAPIの提供に相当の支障があると判断した場合はアクセス制限や機能自体の停止等の処置を行うことがあります。


改訂履歴

改訂日 更新内容
2024/4/9 配信予約APIにoneClickUnsubscriptionReadyを追加
2024/1/26 oneClickUnsubscriptionReadyの説明を修正
2023/12/12 APIを追加
・配信解除依頼リスト取得API
・全配信解除依頼リスト取得API
Synergy! メールAPIリクエストの補足事項の記述を修正
メール配信実施API・指定の配信IDのメール配信実施APIにoneClickUnsubscriptionReadyを追加
2023/10/10 配信状態取得APIのstatusの説明を修正
2023/09/12 Synergy! メールAPIリクエストの補足事項の記述を修正
全配信エラー結果取得APIを追加
2023/06/22 Customer.synergyidの最大値についての記述を修正
2023/05/16 HTTPステータスコード、APIコール数、通数制限についての記述を修正
2023/04/11 APIを追加
・予約配信用の配信先リストの登録
・配信先リスト情報取得
・配信予約
配信状態取得APIで返却されるstatusの値を追加
配信設定削除APIで予約中の配信設定を削除した場合の説明を追加
メール配信実施APIおよびメール配信設定作成APIのbodyTextとbodyHtmlにサイズ上限の説明を追加
指定の配信IDのメール配信実施APIで配信予約中の配信IDを指定した場合の説明を追加
メール配信実施のJSONプロパティ deliveryData[] におけるプロパティ名の制限についての説明を追加
エラーコード追加(10022~10035)
「埋め込みコマンドを使用する」にCSV形式の配信先リスト例を追加
「APIコール数、通数制限について」に注意事項を追記
TLS対応バージョンを修正
「Synergy! メールAPIから返されるエラー定義」でerrors[].codeの型をStringに修正
2022/11/09 envelopeFromに関する記述を削除
2022/04/15 配信設定削除APIを追加
2020/04/30 配信結果取得APIを追加
2019/11/20 「埋め込みコマンドを使用する」に注意事項を追記
2019/11/12 APIを追加
・メール配信設定作成
・指定の配信IDのメール配信実施
配信結果取得APIに期間指定パラメータを追加
エラーコード追加 (10020:期間指定パラメータ不正)
エラーコード10018に指定可能範囲を追記
配信エラー結果取得APIのレスポンスサンプルの誤りを修正
[正]
"Synergy!ID","配信エラー日時","配信エラー理由"
"493","2016-09-12 08:21:38","UNKNOWN_USER"
[誤]
"Synergy!ID","配信エラー日時","配信エラーID","配信エラー理由"
"493","2016-09-12 08:21:38","123","4700","UNKNOWN_USER"
2019/10/28 サービス名称を修正
・正「Synergy! メールAPI」
・誤「Synergy!メールAPI」
メール配信実施のJSONプロパティ deliveryData[] における、Customer.synergyid の指定可能範囲を追記
メール配信実施のレスポンスサンプルを修正
・正 "htmlClickFeedbacks":[{"id": 15,"url": "http://example.com/"}]
・誤 "htmlClickFeedbacks":[{"id": 15,"url": "http://example.com/"]]
2019/10/07 推奨APIコール数を追記
2019/08/16 エラーコードを追記
配信結果取得APIレスポンスのCSV仕様を変更
文書全体の構成を変更
2019/07/08 認証API仕様を追記
2019/05/29 初版