Comelメールマガジン
送信システムAPI仕様書
2024/10/18 Version1.0
サービス利用規約
2
共通仕様
API全体を通して、1秒に1回以上呼び出された場合、予告なく利用制限を行なう可能性があります。
APIメソッドが異なるものを利用したとしても制限に抵触する可能性があります。また、サーバーに対して多大な負荷を
与えるような利用を行なった場合、アクセス自体を制限することもあります。
利用にあたっては、Comel管理画面内にある、AuthkeyとSecretKeyが必要です。
エンドポイントは、https://comel.app/app/apiです。
APIはRESTに準拠し、HTTPプロトコル (SSL/TLS) を用いて操作を行うものとします。
文字コードは UTF-8のみ対応とします。
予約配信も可能ですが、分単位で管理をしているため、秒を指定しても無視されます。
また同時間帯で送信予定が合った場合、送信速度が低下することがあるほか、時間をずらして送信することがあります。
1日辺りの最大送信可能メール数が決まっています。送信可能数をオーバーして登録した場合、エラーとなります。
予約配信の場合、実際の配信日の送信可能通数を減じます（登録した当日の配信可能数を減じるものではありません）。
本仕様書は ComelのAPIを利用した操作について、利用できるAPI及びパラメータなどを記述したものです。
本APIを利用することで、Comelの機能を別のシステムから利用することができます。
利用規約はこちらからご覧になれます。
Token要求(Key)
送信内容送出(Token,JSON)
送信ID返却(Id)
ステータス要求(Id,Token)
ステータス返却(Status)
エラーアドレス要求(Id,Token)
エラーアドレス返却(Addresses)
Mail Server
Token返却(Token)
送信内容格納
送信
API Server
API Client
・トークン（Token）の取得
エンドポイントに対して送出を行う。
TokenはBearer認証として、HTTPのAuthorizationヘッダに指定して送出する
メソッド
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、
レスポンス
401
200
406
・認証に利用するTokenの取得 ・有効期限前に再度呼び出すと新しい有効期限のTokenを発行
・Token取得のためのログイン認証 ・有効期限を越えるときに再取得
POST
/login
・authkey:String ・secretkey:String
form-data
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
・正常 ・JSON ・result:String：処理結果。空文字
・token:String：トークン ・expire:Int：有効期限（UNIXタイム）
・システムによるログイン制限 ・JSON
・result:String：処理結果、エラー文字列
正常に受理され、トークンを提供。
200
{
"result": "トークンが生成されました",
"token": "a.1.1676000161.2201571746863e5b94929cb7.cf048977cc75f0d7621f7e6fc53754663e1345f685b72eba0aa8c3010b2a88ee804bcb87922c0842549fd699ae2d763f8f27254315467c446cd1baae05d7d455",
"expire": 1676000161
}
・result(string): ユーザー向けのメッセージ文字列
トークンが生成されました」のみ。
認証エラー。 authKey か secretKey が間違っている。もしくは存在しない。
401
{
"result": "認証パラメータが間違っています"
}
システムによるログイン制限。
406
{
"result": "「利用制限中です」"
}
DB エラー。
500
・token(string): 他 API で Authorization ヘッダーに設定する文字列
・expire(number): このトークンが使用できなくなる
UNIX TIME (単位：秒)
・result(string): ユーザー向けのメッセージ文字列。
「必要パラメータが足りません」
「認証パラメータが間違っています」のいずれか。
・result(string): ユーザー向けのメッセージ文字列。
「利用制限中です」のみ。
・result(string): DB エラーが発生しました
{
"result": "DB エラーが発生しました"
}
3
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
メールマガジンとして送信する内容を登録。登録した段階で利用可能通数が引かれる
・送信内容登録 ・添付ファイルは総合計で20MBまで
POST
/registmail
・subject(string): 必須。件名。
・ body(string): 必須。本文。
・returnPath(string): 必須。エラー発生時に戻ってくる return パス。
・from(string): 必須。送信元メールアドレス。実際の From: メールヘッダーと同じように、
送信者名を指定する場合は送信者名 <test@example.com> のように指定。
・immediate(boolean): 必須。trueなら即時配信。 falseなら予約配信。
・prohibited（int）：任意。1なら禁止リストを無視して送信、0なら無視しない。
デフォルトは無視しない。
・schedule(number): immediate が falseの時にのみ必須。送信予定時刻を UNIX TIME (単位：秒)で指定する。過去は指定できない。
・delivery({to: string, replace: {word: string, content: string}[]}[]): 必須。
空配列も受け付けない。詳細は下記。
・ attachment({filename: string, filesize: number, filetype: string, filebody: string}[]): 任意。
省略、または空配列を指定すると添付ファイルをつけない。詳細は下記。
・delivery の中身
・ to(string): 必須。送信先メールアドレス。形式もメールアドレスとして正しくなくてはならない。
・replace({word: string, content: string}[]): 任意。差し込み文章。詳細は下記。
件名と本文が対象だが、このパラメータを省くと置換されず、そのまま {変数名} として残る。
上記の例では、「to@example.com」に対して送信されるメールの件名、本文中にある「{var001}」はそのまま残る。
・replace の中身
・word(string): 必須。変数名。置換対象文字列。 {と} は含まない。
・content(string): 必須。差し込み対象の置換後文字列。
・attachment の中身
・filename(string): 必須。添付時に使用されるファイル名。
・filesize(number): 必須。添付ファイルのサイズ（単位：バイト）。
・filetype(string): 必須。ファイルの MIME Type。
・filebody(string): 必須。ファイルを Base64 形式に変換したもの。先頭に
「data:image/png;base64,」のような文字を付けないように注意。
JSON
・送信内容登録
受信時HTTPステータス、
レスポンス
406
・エラー ・JSON ・result:String：処理結果、エラー文字列
200
・正常 ・JSON ・result:String：処理結果。空文字 ・sentid:Int：送信ID
401
・Token認証エラー ・JSON ・result:String：処理結果、エラー文字列
400
・送信可能数オーバー ・JSON ・result:String：処理結果、エラー文字列
409
・エラー。ファイルサイズ容量オーバー ・JSON
・result:String：処理結果、エラー文字列
4
{
"subject":"テストメール {var001}",
"body": "本文メッセージです\nこれはテストです{var002}\n件名に差し込まれたのは「{var001}」",
"returnPath": "return@example.com",
"from": "サンプル送信者 <from@example.com>",
"immediate": false,
"schedule": 1676005500,
"delivery": [
{
"to": "to@example.com",
"replace": [
{
"word": "var001",
"content": "件名差し込みテスト文字列"
},
{
"word": "var002",
"content": "本文差し込みテスト文字列"
}
]
},
{
"to": "to2@example.com",
"replace": [
{
"word": "var002",
"content": "本文差し込みテスト文字列"
}
]
}
],
"attachment": [
{
"filename": "テスト01.png",
"filesize": 297,
"filetype": "image/png",
"filebody": "iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAIAAACRXR/mAAAA7klEQVRYhc3QSQrEMBAEwdT8/889B4MRXmSp1Vvd
E4JquE1E1G0zdPTbMrXmwto04fHWvglzlokJW5aVCUOWoQkrlq0JE5a5iX2Wh4lNlpOJHZafCTXL1YSO5W1CwQowscqKMbHECjMxz4o0M
ckKNjHDijfxyUoxMWZlmRiwEk28sXJNPLLSTdxZFUxcWEVM9Kw6Jk5WKRMHq5oJaAVNwE9d+plERMlyNaF7y9uEghVgYpUVY2KJFWZin
hVpYpIVbGKGFW/ik5ViYszKMjFgJZp4Y+WaeGSlm7izKpi4sIqY6Fl1TJysUiYOVjUT8AeQ8pZDmBtgggAAAABJRU5ErkJggg=="
},
{
"filename": "テスト02.png",
"filesize": 155,
"filetype": "image/png",
"filebody": "iVBORw0KGgoAAAANSUhEUgAAAJYAAACWBAMAAADOL2zRAAAAD1BMVEUAANmTJv9TFe5KE+wqC+S9LKSdAAAAR
0lEQVRo3u3MMQ0AIAwAMBJmAAcECxiYf1VY2EvWCugAAIC+4lZk6ZqrYrtcLpfL5XK5XC6Xy+VyuVwul+uTK05FDgAAaOsB5N7Mwu0qbo
EAAAAASUVORK5CYII="
}
]
}
送信例
5
・受信時 HTTP ステータス、レスポンス
正常に受理され、送信IDを提供。
200
{
"result": "送信を開始しました",
"sentid": 1676005084854249
}
・result(string): ユーザー向けのメッセージ文字列。
「送信を開始しました」「送信予約が完了しました」のいずれか。
Token 認証エラー。トークンが不正、存在しない、有効期限切れのいずれか。
401
{
"result": "認証に失敗しました"
}
バリデーションエラー。送信パラメータが間違っている場合に発生する。
406
{
"result": "「subjectは必須です」"
}
ファイルサイズ容量オーバー 。
409
・sentid(string): status, erraddress API で sentid に設定する ID
・result(string): ユーザー向けのメッセージ文字列。「認証に失敗しました」のみ。
・result(string): ユーザー向けのメッセージ文字列。
様々なメッセージが入る。
・result(string): ユーザー向けのメッセージ文字列。 「ファイルサイズが{{設定値}}バイトを超過しています」のみ。
{
"result": "「ファイルサイズが2,000,000バイトを超過しています」"
}
・パラメータによってクライアントより自己申告されたファイルサイズと
・Base64 から復元した実際のファイルサイズどちらか片方でもオーバーしていたら受理されずにこの応答となる。
DB エラーor 添付ファイル保存エラー。
500
・result(string): ユーザー向けのメッセージ文字列。「DB エラーが発生しました」「{{ファイル名}}の保存に失敗しました」のいずれか。
{
"result": "DB エラーが発生しました"
}
・DB で INSERT に失敗した
・添付ファイルをサーバーに保存することができなかったのいずれかで発生
6
・ステータス取得
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、レスポンス
401
200
409
送信状況の取得。送信前、送信中、送信完了
ステータス取得
GET
/status
sentid:Int
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
・正常 ・JSON ・result:String：ステータス（'wait', 'sending', 'complete'）
・指定されたsentidが存在しない ・JSON
・result:String：処理結果、エラー文字列
・受信時 HTTP ステータス、レスポンス
該当するメールが存在し、スターテスを返却。
200
{
"result": "complete"
}
・result(string): ステータスを表す文字列。「‘wait’ ‘(送信 前)」「’sending’ (送信中)‘」「’complete’ (送信完了)’」 のいずれか。
Token 認証エラー。トークンが不正、存在しない、有効期限切れのいずれか。
401
{
"result": "認証に失敗しました"
}
sentid で指定されたデータが存在しない 。または sentid が指定されていない。
409
・result(string): ユーザー向けのメッセージ文字列。「認証に失敗しました」のみ。
・result(string): ユーザー向けのメッセージ文字列。「該当するメール配信が存在しません」「パラメータ「sentid」が存在しません」のいずれか。
{
"result": "「該当するメール配信が存在しません」"
}
7
・送信キャンセル
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、
レスポンス
401
200
406
送信前のキャンセル。送信可能通数は元に戻される
送信キャンセル
GET
/cancel
sentid:Int
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
・正常 ・JSON ・result:String：処理結果。空文字
・指定されたsentidが存在しない ・JSON
・result:String：処理結果、エラー文字列
409
・指定されたsentidが存在しない ・JSON
・result:String：処理結果、エラー文字列
・受信時 HTTP ステータス、レスポンス
該当するメールが存在し、送信をキャンセル。
200
{
"result": ""
}
・result(string): 空文字固定。
Token 認証エラー。トークンが不正、存在しない、有効期限切れのいずれか。
401
{
"result": "認証に失敗しました"
}
sendid で指定されたデータが存在するが、既に送信済 。または送信中。
406
{
"result": "「該当するメール配信が存在しません」"
}
sendid で指定されたデータが存在しない 。または sendid が指定されていない。
409
・result(string): ユーザー向けのメッセージ文字列。「認証に失敗しました」のみ。
・result(string): ユーザー向けのメッセージ文字列。「既に送信済です」「既に送信中です」のいずれか。
・result(string): ユーザー向けのメッセージ文字列。該当するメール配信が存在しません」「パラメータ「sentid」が存在しません」のいずれか。
{
"result": "「該当するメール配信が存在しません」"
}
8
・送信時にエラーになったアドレス取得
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、レスポンス
401
409
送信時にエラーとなったアドレスの取得
エラーアドレス取得
GET
/erraddress
sentid:Int
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
・指定されたsentidが存在しない ・JSON ・result:String：処理結果、
エラー文字列
200
・正常 ・JSON ・result:String：ステータス ・address:Array：メールアドレス
・受信時 HTTP ステータス、レスポンス
該当するメールが存在し、スターテスを返却。
200
{
"result": "complete",
"address": ["to@example.com", "to2@example.com "]
}
・result(string): ステータスを表す文字列。「‘wait’ ‘(送信前)」「’sending’ (送信中)‘」「’complete’ (送信完了)’」のいずれか。
Token 認証エラー。トークンが不正、存在しない、有効期限切れのいずれか。
401
{
"result": "認証に失敗しました"
}
sendid で指定されたデータが存在しない 。または sendid が指定されていない。
409
・result(string): ユーザー向けのメッセージ文字列。「認証に失敗しました」のみ。
・result(string): ユーザー向けのメッセージ文字列。該当するメール配信が存在しません」「パラメータ「sentid」が存在しません」のいずれか。
{
"result": "「該当するメール配信が存在しません」"
}
・address(string[]): 送信時エラーとなったメールアドレスの一次元配列。
9
・送信可能通数
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、
レスポンス
401
今日の送信可能数と残り送信可能数
送信可能通数取得
GET
/remaining
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
200
・正常 ・JSON ・limit:Int：送信可能数 ・remaining:Int：残り送信可能数
・受信時 HTTP ステータス、レスポンス
残りの通数情報を提供
200
{
"limit": 50,
"remaining": 45
}
・limit(number): 本日の送信可能数。
Token 認証エラー。トークンが不正、存在しない、有効期限切れのいずれか。
401
{
"result": "認証に失敗しました"
}
・result(string): ユーザー向けのメッセージ文字列。「認証に失敗しました」のみ。
・remaining(number): 本日の残り送信可能数。
10
機能名
・禁止リストへの登録
11
受信時HTTPステータス、
レスポンス
200
・正常 ・JSON ・result:String：処理結果
401
・認証エラー ・JSON
409
・メールアドレス形式が正しく無いか、禁止リストに登録されていない
・JSON ・result:String：処理結果、エラー文字列
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
禁止リストに対してメールアドレスを登録する
禁止リストの登録
POST
/regprohibited
JSON
mail:String :禁止リストに登録するメールアドレス
受信時HTTPステータス、
レスポンス
200
・正常 ・JSON ・result:String：処理結果
401
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
・メールアドレス形式が正しく無いか、既に登録済み ・JSON
・result:String：処理結果、 エラー文字列
409
・禁止リストに登録されているメールアドレス取得
受信時HTTPステータス、
レスポンス
200
・正常 ・JSON ・result:String：処理結果 ・address:Array : 登録されているメールアドレスを配列で返却（未登録の場合は空配列が返る）
401
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
説明
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
禁止リストに登録されているメールアドレスを取得する
禁止リストに登録されているメールアドレス取得
GET
/getprohibited
機能名
機能名
・禁止リストからのメールアドレス削除
説明
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
禁止リストに登録されているメールアドレスを削除する
POST
/deleteprohibited
機能名
JSON
mail:String :禁止リストから削除するメールアドレス
禁止リストから指定したメールアドレスを削除する
・サプレッションリストの取得
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、
レスポンス
サプレッションリストに登録されているメールアドレスを取得する
サプレッションリストに登録されているメールアドレス取得
GET
/suppression
200
・正常 ・JSON ・result:String：処理結果 ・address:Array : 登録されているメールアドレスを配列で返却（未登録の場合は空配列が返る）
＊メールアドレスは重複して返される可能性がある
401
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
409
・メールアドレス形式が正しく無いか、サプレッションリストに登録されていない ・JSON ・result:String：処理結果、エラー文字列
・サプレッションリストからの削除
説明
機能名
送信メソッド
エンドポイント
送信時パラメータ
リクエスト形式
受信時HTTPステータス、
レスポンス
サプレッションリストから指定したメールアドレスを削除する
サプレッションリストに登録されているメールアドレスを削除する
POST
/deletesuppression
409
・メールアドレス形式が正しく無いか、サプレッションリストに登録されていない ・JSON ・result:String：処理結果、エラー文字列
mail:String :サプレッションリストから削除するメールアドレス
JSON
200
・正常 ・JSON ・result:String：処理結果
401
・認証エラー ・JSON ・result:String：処理結果、エラー文字列
12
お問い合わせ先
・お申し込み・お問い合わせはホームページへ
13
・変更履歴
2024/10/18
Rev0.1
制定
株式会社コムセント
〒150-0002 東京都渋谷区渋谷 1-3-18 B305