Mailgun から移行
Mailgun の SDK はそのままに、OpenEmail 経由で送信します。ベース URL とキーを変えるだけで、送信コードは今のままです。
変更する箇所
SDK の向き先を https://api.openemail.uk/compat/mailgun にし、Mailgun のキーの代わりに emails:send 権限を持つ OpenEmail の API キーを渡します。キーは同じ HTTP Basic 認証のパスワードとして送られ、ユーザー名は確認されません。パスのドメインはワークスペースのドメインのいずれかでなければならず、メッセージを送れるかどうかは、OpenEmail のどこでもそうであるように From アドレスで決まります。
import formData from 'form-data'import Mailgun from 'mailgun.js' const mailgun = new Mailgun(formData)const mg = mailgun.client({ username: 'api', key: process.env.OPENEMAIL_API_KEY, url: 'https://api.openemail.uk/compat/mailgun',}) await mg.messages.create('acme.com', { from: 'Acme Billing <[email protected]>', to: ['[email protected]'], subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Ruby では、2 番目の引数にスキームなしでホストとパスを指定します。PHP では、SDK は渡されたエンドポイントのホストしか使わないため、パスは php-http の AddPathPlugin で追加します。このプラグインは SDK と一緒にインストールされています。公式の Python パッケージは、ホストが Mailgun のものではないという警告をログに出すことがありますが、送信はそのまま行います。また 429 や 5xx で失敗したリクエストを再試行するため、バッチの一部がすでに送られた後は、OpenEmail は 5xx ではなく 400 を返します。
対応関係
提供するエンドポイントは POST /v3/{domain}/messages で、添付に必要な multipart/form-data か、application/x-www-form-urlencoded で受け付けます。名前が [] で終わるフィールドは、それを除いた名前で読み取ります。
| Mailgun | OpenEmail では |
|---|---|
| from | 送信者と、その名前。 |
| to | 受信者。繰り返し指定するか、カンマで区切ります。cc と bcc と合わせて、1 通あたり最大 50 人です。 |
| subject | 件名。 |
| html | HTML 本文。text はテキスト本文になり、どちらか一方か template が必要です。 |
| attachment | ファイルは最大 20 個、合計 5 MB まで。 |
| inline | HTML がファイル名を使って cid: として参照している画像は、その位置に埋め込まれます。それ以外のインラインファイルは通常の添付として届きます。 |
| o:tag | tag、tag_2 のように名前が続くタグで、それぞれにタグが 1 つ入ります。 |
| v: | 各変数は、その名前と値を持つタグになります。o:tag と合わせて、1 通あたり最大 10 個です。 |
| o:deliverytime | 予約送信で、最大 1 年先まで。すでに過ぎた時刻なら即時に送信されます。 |
| o:tracking | o:tracking-clicks、o:tracking-opens とともに、そのメッセージのトラッキングをオン・オフします。htmlonly はオンとみなします。 |
| o:testmode | yes は、oe_test_ キーと同じく、配信せずに送信済みとして記録します。 |
| h:Reply-To | 返信先アドレス。それ以外の h: フィールドはカスタムヘッダーになります: X-*、List-*、Precedence、Auto-Submitted、Importance、Priority、Feedback-ID。 |
| recipient-variables | バッチ送信です。to の各アドレスにそれぞれ別のメッセージが送られ、%recipient.key% にはそのアドレスの変数が、%recipient% にはそのアドレスが入ります。cc と bcc は各メッセージに付きます。値のないプレースホルダーはそのまま残ります。 |
| template | OpenEmail テンプレートのスラッグまたは ID (tpl_...) で、t:variables、それがなければ h:X-Mailgun-Variables の値が差し込まれます。t:version はバージョンを番号で選びます。 |
拒否されるものとその理由
htmlやtextと併用したtemplate。OpenEmail のテンプレートが本文全体を提供するためです。バージョン番号でないt:versionも拒否されます。o:deliverytime-optimize-periodとo:time-zone-localize。OpenEmail は受信者ごとに送信時刻を選ばないためです。ほかのh:X-Mailgun-ヘッダーは Mailgun への指示なので、対応するo:オプションを代わりに使ってください。- 単独の
amp-html。htmlやtextと一緒なら、それらがメッセージを伝えるので、amp-htmlは使われません。 - 複数の返信先アドレス、10 個を超えるタグ、英字・数字・
_・-以外を含むタグ名、100 人を超える受信者のバッチ。Mailgun は 1,000 人まで受け付けるので、大きなバッチは分割してください。
o:dkim、o:require-tls、o:skip-verification、o:sending-ip、o:sending-ip-pool、o:tracking-pixel-location-top、o:archive-to、o:deliver-within、t:text は受け付けますが、何も変わりません。
レスポンスとエラー
- 送信は 200 を返し、メッセージ
Queued. Thank you.とidを含みます。idは山かっこで囲んだ OpenEmail のメッセージ ID で、GET /emails/{id}と Webhook は山かっこなしで使います。バッチ送信は受信者ごとに 1 通を作り、それぞれ別の ID を持ち、最初のものを返します。Idempotency-Keyヘッダーは API のほかの部分と同じように動きます。 - キーがないか不明な場合は、プレーンテキスト
Forbiddenで 401 を返し、ワークスペースにないドメインにはDomain not foundで 404 を返します。それ以外はすべてmessageとして返ります。送信できないメッセージには 400、emails:sendのないキー、キーが使えない From アドレス、まだ送信できないドメイン、送信枠を使い切ったワークスペースには 403、25 MB を超える本文や 5 MB を超える添付には 413 です。 - ほかの受信者が受け付けられた後でバッチの 1 人が失敗した場合、エラーはすでに送信したメッセージを示し、400 を返します。再試行する SDK が同じメッセージを二重に送らないようにするためです。