MailLogic API ドキュメント

公開APIは13操作に対応し、用途に応じて2種類の認証を使い分けます。

• Personal Access Token（PAT／自動化トークン）：ドメイン、メールアカウント、使用状況、メールログ、DNS確認、転送テストなどの管理操作に使用します。スコープで権限を指定し、対象ドメインを制限できます。
• ドメインAPIキー：送信ドメインのSend APIとBatch Send APIに使用します。PATではSend／Batch Sendを利用できません。ドメインAPIキーでは管理操作を利用できません。

ベースURL：https://api.maillogic.io。HTTPSを使用し、秘密情報はサーバー側で保管してください。ブラウザーのコードやソース管理には含めないでください。

管理リクエストには、mlpat_で始まるトークンをAuthorization: Bearer $MAILLOGIC_TOKENで指定します。ダッシュボードの自動化トークンを開き、権限と対象ドメイン（すべて／選択したドメインのみ）を指定して作成してください。秘密情報は作成時に一度だけ表示されます。すぐにコピーしてください。ダッシュボードで作成したトークンの有効期限は90日です。期限切れ・失効済みのトークンは401になります。失効操作後は直ちに認証できなくなります。

各スコープは独立しています。DNS確認や転送テストの作成権限だけでは読み取りはできません。ドメイン制限付きトークンで参照できるのは、許可された所有ドメインのみです。対象外のリソースは404になります。使用状況はアカウント全体の情報のため、usage:readにはドメイン制限のないトークンが必要です。

送信にはmlk_で始まるドメインAPIキーを使い、Authorization: Bearer $MAILLOGIC_DOMAIN_KEYまたはX-API-Key: $MAILLOGIC_DOMAIN_KEYを指定します。PATと相互に代用することはできません。

以下はPOSIXシェルとcurlの例です。ドメイン制限なしでdomains:read、email-accounts:read、usage:readを持つPATを作成してください。トークンとIDのプレースホルダーを自分の値に置き換えます。

ドメイン・メールアカウントの一覧は{"data": [...], "next_cursor": null}、詳細はオブジェクトを直接返します。IDはUUIDです。一覧はlimit（1〜200、既定50）とcursorに対応します。同じトークン・フィルターを使い、返されたnext_cursorをそのまま次のcursorに指定してください。nullなら最終ページです。クエリ値のエンコードにはcurlの--data-urlencodeを使用します。ログも同じ一覧形式です。

GET /v1/domainsはname（完全一致、大文字小文字を区別せず末尾のドットを無視）とownership_status（pending、verified、revoked）で絞り込めます。GET /v1/domains/{id}は1件のドメインを返します。

フィールド：id、name、ownership_status、forwarding_ready、smtp_ready、dns、last_checked_at、created_at、updated_at。読み取り操作は保存済みの観測結果を返します。リアルタイムの確認や配信保証ではありません。

• forwarding_readyは、確認済みであること、所有権が検証済みであること、必要な2つのMXレコードが確認できていることに基づきます。送信用SPF／DKIM／DMARCの準備状態には依存しません。
• BasicなどSMTP利用権のないアカウントでは、"smtp_ready": nullは対象外を意味します。送信用のdns.spf、dns.dkim、dns.dkim_smtp1、dns.dkim_smtp2、dns.dmarcもnullです。
• SMTP利用権のあるアカウントのsmtp_readyは真偽値です。falseは準備条件を満たしていない状態、trueは保存済みのドメイン状態とアカウントの送信ポリシーが送信を許可する状態です。送信者ごとの確認は別途必要です。DNS確認後の送信用観測値は真偽値ですが、未確認の保存済みDNS値はnullになる場合があります。
• dns.mx_10とdns.mx_20は全プランの転送に適用されます。確認済みDNS値のfalseは対象だが条件未達、trueは条件を満たしていることを意味します。

DNSと所有権の再確認

POST /v1/domains/{id}/check-dnsにはdomains:check-dnsが必要です。本文やIdempotency-Keyは不要です。保存済みのDNS・所有権状態を更新し、メール設定の同期処理を実行する場合があります。

レスポンスはchecks、ownership（verified、state）、checked_at、更新後のdomainです。今回のchecksにはmx_10、mx_20、mx、unexpected_mx、spf、dkim、dkim_smtp1、dkim_smtp2、dmarcが含まれます。SMTP利用権がなければ送信用の確認値はnullです。

404は参照できないドメイン、409は別アカウントが検証済みの所有権を持つ場合、429は頻度制限や同時実行（Retry-Afterに従う）、503はDNS・ストレージ・連携先の状態を確定できない場合です。503でも更新済みの場合があります。detail.params.state_persistedがあれば確認し、同じ操作を再試行してください。

GET /v1/email-accountsは任意のdomain_id・activeで絞り込めます。GET /v1/email-accounts/{id}は1件を返します。どちらもemail-accounts:readが必要です。この権限では転送先も参照できます。

フィールド：id、domain_id、address、nullを許容するdisplay_name・forward_to、active、smtp_enabled、forwarding_test_eligibility、created_at、updated_at。smtp_enabledは設定値であり、送信可能であることの保証ではありません。

domain_idは所属ドメインのIDです。転送テストにはメールアカウントのidをemail_account_idとして指定します。設定済みのエイリアスと転送先が使われます。実行可否はeligibleと、nullを許容するreasonで返します。理由はownership_mismatch、username_inactive、forwarding_destination_missing、domain_ownership_unverified、inbound_mx_unverifiedです。作成時に実行条件を再確認します。

GET /v1/usageにはusage:readとドメイン制限のないアクセスが必要です。measured_at、plan、plan_name、email_accounts、smtp、smtp_sending_stateを返します。

email_accounts.usedは無効なものを含む全メールアカウント数、email_accounts.limitはプランの上限です。SMTP利用権がなければsmtpはnullです。それ以外ではunit（recipients：受信者数）、period_start、nullを許容するperiod_end、rolling_period、included_limit、used、included_used、included_available、purchased_available、reserved、usable_availableを含みます。利用可能数はプラン付属分と購入分から予約済み分を差し引いた値です。

smtp_sending_stateはnot_entitled、suspended、billing_operation_in_progress、credits_exhausted、availableのいずれかです。アカウントのポリシーと残量を表す値であり、送信者・ドメインの条件や受付制限は別途適用されます。使用状況の取得に失敗した場合は、利用数を0とするのではなくエラーを返します。

GET /v1/logs?domain_id=$DOMAIN_IDにはlogs:read、対象ドメインへのアクセス、現在の検証済み所有権、ログ機能を含むプランが必要です。プラン対象外は403、所有権未検証は409になる場合があります。現在の所有権に帰属すると確認できる活動のみを返します。

ページ分割に加え、since（含む）、until（含まない）、search、activity_type（forwarding／outbound）、statusで絞り込めます。日時はUTCまたはオフセット付きのRFC3339形式です。検索期間は最大30日で、既定は最初のページを要求した時刻までの30日間です。これは検索期間の上限であり、保存期間の保証ではありません。検索はアドレス・識別情報の大文字小文字を区別しない部分一致で、本文検索ではありません。

各項目：id、occurred_at、activity_type、nullを許容するsender・recipient・recipient_count、status、nullを許容するreason（smtp_code、enhanced_status）。occurred_atは転送の発生時刻または送信先への送信受付時刻で、最新の配信時刻ではありません。メール本文は含みません。

状態：submitted、accepted、deferred、bounced、failed、suppressed、unknown、forwarded、blocked。submittedはローカルでの送信受付、forwardedは転送処理への引き渡し、acceptedは信頼できる受信先SMTP受付の確認を表します。受信トレイへの到達を意味しません。

POST /v1/forwarding-testsにはforwarding-tests:create、1つだけのIdempotency-Keyヘッダー、JSONのemail_account_id（UUID）が必要です。任意のlocaleはen（既定）またはjaです。キーは空白を除く印字可能ASCII文字1〜128文字で、大文字小文字を区別します。サーバーが生成する診断メールを、指定したエイリアスから設定済み転送先へ送ります。

永続的に受け付けた時点で202を返します。一時的なキュー障害中も同様です。Locationは/v1/forwarding-tests/{id}を指します。同じアカウントで同じキー・同じリクエストを再送すると、追加送信せず同じテストを返し、Idempotency-Replayed: trueが付きます。再取得は少なくとも30日間対応します（replay_expires_atを参照）。同じキーで内容を変更すると409です。同じエイリアスに別のテストを作成すると、5分間の待機制限により429とRetry-Afterが返る場合があります。

GET /v1/forwarding-tests/{id}にはforwarding-tests:readが必要です。保存された結果を確認・更新する操作であり、メールを再送しません。処理中はpoll_after_msに従ってポーリングしてください。処理中の状態はqueued、submitting、checking、最終状態はconfirmedとfailedです。confirmedはMailLogicが転送先SMTPでの受付を観測したことを意味し、受信トレイへの到達を保証しません。タイムアウトや不確定な結果だけでは未配信と断定できません。

両操作のレスポンス：id、nullを許容するemail_account_id・domain_id、alias、destination、locale、status、nullを許容するfailure_code、created_at、nullを許容するsubmitted_at・confirmed_at・failed_at、monitoring_deadline_at、replay_expires_at、nullを許容するpoll_after_ms。ドメイン制限付きトークンでは、ドメイン削除後に過去のテストを参照できません。

PATではなくドメインAPIキーを使います。対象ドメインのAPIセクションでキーを作成してください。対応プラン、キーのドメインに属する有効な送信者、SMTP有効化とパスワード設定、検証済みの所有権・送信用DNSが必要です。

• POST /v1/send：フォーム形式でfrom_email、繰り返し指定できるto_email、subject、任意のtext_content、html_content、display_name、attachmentsを送ります。Idempotency-Keyは任意です。200レスポンスにはstatus、message、message_id、from_email、to_email、受信者配列（accepted_recipients、rejected_recipients、suppressed_recipients）と件数を含みます。
• POST /v1/batch-send/preview：JSONの下書きを検証し、プレビュー、受信者数、ヘッダー、参照変数、警告、利用枠を返します。送信はしません。
• POST /v1/batch-send：JSONの下書きと必須のIdempotency-Keyで送信を依頼します。202とbatch、duplicate、quota、Locationヘッダーを返します。
• GET /v1/batch-send/{batch_id}：バッチオブジェクトと進捗・結果の件数を返します。

バッチの下書きはfrom_email、subject_template、text_template／html_template、emailとvariablesを持つrecipientsで構成します。詳しい例、制限、冪等性、レスポンスはSend API・Batch Send APIガイドを参照してください。送信受付の成功は最終的な配信を保証しません。

管理APIのエラー形式は次のとおりです。detail.request_idはレスポンスヘッダーのX-Request-IDと一致します。お問い合わせ時に添えてください。管理APIの成功レスポンスにもこのヘッダーが付きます。送信APIのエラー形式は別契約です。送信ガイドを参照してください。

• 401：PATが未指定、無効、期限切れ、または失効済み（WWW-Authenticate: Bearer）。
• 403：スコープ不足、制限付きトークンでのアカウント全体の使用状況取得、またはプラン・アクセス権不足。
• 404：リソースが存在しない、別アカウントに属する、またはトークンの対象ドメイン外。
• 409：所有権・実行条件の競合、または同じIdempotency-Keyで異なる入力を送信。
• 422：パラメーター、UUID、cursor、日時範囲、本文、冪等性ヘッダーが不正。
• 429：頻度制限、同時実行、または転送テストの待機制限。Retry-After秒待って再試行してください。
• 503：依存サービスや操作が一時的に利用不可。Retry-Afterがあれば従ってください。転送テストの受付が不確定な場合は、同じキーと内容で再試行してください。

現在の管理API認証制限は接続元ごとに120回／分、トークンの認証情報ごとに60回／分、認証済みアカウントごとに300回／分です。操作別の制限も適用されます。頻繁なポーリングを避け、返された再試行の案内に従ってください。通常のSend APIには別途、アカウント全体で新規SMTP送信受付を毎秒1回に制限する仕組みがあり、超過時は429とRetry-Afterを返します。

公開OpenAPIスキーマは、13操作のリクエスト・レスポンス形式と認証要件を示す機械可読の契約です。トークンなしで参照できます。