SendGrid から移行
SendGrid の SDK はそのままに、OpenEmail 経由で送信します。ベース URL とキーを変えるだけで、送信コードは今のままです。
変更する箇所
SDK の向き先を https://api.openemail.uk/compat/sendgrid にし、SendGrid のキーの代わりに emails:send 権限を持つ OpenEmail の API キーを渡します。キーは同じ Authorization: Bearer ヘッダーで送られます。メールを送る呼び出しはそのままで、メッセージを送れるかどうかは、OpenEmail のどこでもそうであるように From アドレスで決まります。
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Node では、まずクライアントにキーを設定し、次にベース URL を設定してから、そのクライアントを mail パッケージに渡します。その後で sgMail.setApiKey を呼ばないでください。ベース URL が SendGrid に戻ってしまいます。SDK はキーが SG. で始まらないと警告しますが、問題はありません。Python、Ruby、PHP では、ホストの末尾にスラッシュを付けないでください。
対応関係
提供するエンドポイントは POST /v3/mail/send です。personalizations の各要素は、それぞれ独自の ID を持つ別々の OpenEmail メッセージになるため、1 回のリクエストで送れるのは最大 100 通です。
| SendGrid | OpenEmail では |
|---|---|
| from | 送信者と、その名前。パーソナライゼーションごとに独自の from を指定できます。 |
| personalizations | 1 件につき 1 通です。その to、cc、bcc は合わせて最大 50 人の受信者を持てます。subject、headers、custom_args、send_at、substitutions はそのメッセージにだけ適用されます。 |
| subject | 件名。パーソナライゼーションが独自の件名を設定した場合はそちらが使われます。 |
| content | text/plain はテキスト本文に、text/html は HTML 本文になります。HTML 本文がすでにメッセージを伝えるため、text/x-amp-html は使われません。 |
| attachments | ファイルは最大 20 個、合計 5 MB まで。HTML が cid: として content_id を参照しているインライン画像は、その位置に埋め込まれます。それ以外のインラインファイルは通常の添付として届きます。 |
| reply_to | 返信先アドレス。reply_to_list も、アドレスが 1 つだけなら使えます。 |
| headers | カスタムヘッダー: X-*、List-*、Reply-To、Precedence、Auto-Submitted、Importance、Priority、Feedback-ID。パーソナライゼーションは独自のヘッダーを追加できます。 |
| categories | category、category_2 のように名前が続くタグで、それぞれにカテゴリが 1 つ入ります。 |
| custom_args | 同じ名前と値を持つタグ。パーソナライゼーションの値が優先されます。 |
| send_at | 予約送信で、最大 1 年先まで。すでに過ぎた時刻なら即時に送信されます。 |
| substitutions | 各キーは、そのメッセージの件名、テキスト本文、HTML 本文の中で値に置き換えられます。 |
| template_id | OpenEmail テンプレートの ID (tpl_...) またはスラッグで、dynamic_template_data の値が差し込まれます。 |
| tracking_settings | open_tracking.enable と click_tracking.enable で、そのメッセージの開封とクリックのトラッキングをオン・オフします。 |
| mail_settings | sandbox_mode.enable はリクエスト、送信者、テンプレートを検証し、何も送信せずに 200 を返します。 |
1 通のメッセージに付けられるタグは、カテゴリと custom_args を合わせて最大 10 個です。それを超えるリクエストは切り詰めずに拒否するので、送った内容が黙って失われることはありません。
拒否されるものとその理由
template_idに指定したd-…のような SendGrid のテンプレート ID。テンプレートは SendGrid に残るので、OpenEmail でテンプレートを作り直し、その ID かスラッグを送ってください。template_idと併用したcontent。OpenEmail のテンプレートが本文全体を提供するためです。同じ理由で、テンプレートと併用したsubstitutionsも拒否されます。値はdynamic_template_dataで渡してください。- 複数の返信先アドレス、
reply_toとreply_to_listの併用、テキストと HTML 以外のコンテンツタイプ。カレンダーの招待は.icsの添付として送ってください。 - 有効にした
mail_settings.footerとsections。OpenEmail はメッセージに文章を書き足さないためです。 - 10 個を超えるタグ、英字・数字・
_・-以外を含むタグ名、上のリストにないヘッダー、1 回のリクエストで 100 件を超えるパーソナライゼーション。
asm、batch_id、ip_pool_name、mail_settings のバイパス設定、subscription_tracking、ganalytics、click_tracking.enable_text、open_tracking.substitution_tag は受け付けますが、何も変わりません。ワークスペースの抑止リストにあるアドレスは、バイパス設定の内容にかかわらず常に除外されます。
レスポンスとエラー
- 送信は空の本文で 202 を返し、
X-Message-Idに OpenEmail のメッセージ ID を入れます。これはGET /emails/{id}と Webhook が使う ID です。パーソナライゼーションが複数ある場合は、最初のメッセージの ID が入ります。Idempotency-Keyヘッダーは API のほかの部分と同じように動きます。 - エラーは
message、field、helpのリストであるerrorsとして返ります。送信できないリクエストには 400、キーがないか不明な場合は 401、emails:sendのないキーや、キーが使えない From アドレス、ドメインがまだ送信できない From アドレスには 403、30 MB を超える本文や 5 MB を超える添付には 413、ワークスペースが送信枠を使い切ったときは 429 です。 - 先のパーソナライゼーションが受け付けられた後で 1 件が失敗した場合、エラーはすでに送信したメッセージを示すので、再試行ではそれらを除外できます。