無料トライアルのお申し込みはこちらから。
申込フォームのURL
実際に配信ができるクライアント認証キー、クライアントシークレットを発行いたします。
Synergy! メールAPIは、外部サービスからHTTPS通信を使用して、配信先、配信内容を指定し、メールを配信する事ができるAPIです。
RESTを適用しており、必要なパラメータを指定して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にアクセスする際の流れを表した図です。
Synergy! メールAPIにアクセスするためのアクセストークンを取得します。
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名 | アクセスできる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固定です。 |
メール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分程度時間をあけてから再度アクセスしてください。
メールコンテンツ、配信先リストを指定して配信を開始します。
リクエストサンプル
{ "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から |
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です。 |
指定の配信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 | 配信完了数です。 |
指定の配信IDの配信設定を削除します。削除すると各種配信結果は取得できません。
配信予約中の配信設定を削除した場合、配信先リストとの紐付けが解除され、対象の配信先リストに別の配信設定を紐付けられるようになります。
また、配信予約中の配信設定で、現在日時が配信予約日時の5分前より後の場合、配信が完了するまで削除できません。
メールコンテンツを指定して配信設定を作成します。
リクエストサンプル
{ "encode": "UTF-8", "fromAddress": "support@example.com", "fromName": "カスタマーサポート", "replyAddress": "reply@example.com", "subject": "こんにちは($db.Customer.name$)さん", "bodyText": "お問い合わせは次のURLから |
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の配信設定を利用し、配信先リストを指定して配信を開始します。
指定した配信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です。 |
予約配信用の配信先リストを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です。配信予約時にリクエストに指定します。 |
指定の配信先リスト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になります。 |
指定の配信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から |
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
指定のメール配信の開封確認結果(CSV)を取得します。
レスポンスサンプル
"Synergy!ID","開封日時" "493","2016-09-12 08:21:38" |
指定のメール配信のクリックフィードバック結果(CSV)を取得します。
レスポンスサンプル
"Synergy!ID","クリック日時","クリックID","クリックURL" "493","2016-09-12 08:21:38","123","http//example.com/" |
指定のメール配信の配信エラー結果(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 | その他エラー |
指定のメール配信の結果(CSV)を取得します。
※反映されるには配信から通常、1分ほどかかります。
レスポンスサンプル
"Synergy!ID","配信日時" "10038","2020-04-28 16:20:09" |
指定のメール配信の配信解除依頼リスト(CSV)を取得します。
受信者が購読解除を依頼していますので、次回以降の配信では配信先リストから除外し、配信対象とならないようにしてください。
レスポンスサンプル
"Synergy!ID","配信解除依頼日時" "30114","2023-09-12 12:34:56" |
全配信の配信エラー結果(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" |
全配信の配信解除依頼リスト(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" |
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の両方 |
クリックフィードバックはメール本文に所定の書式で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コール数は最大で秒間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 | 初版 |