SendGrid Web API【入門】

はじめに

SendGridは多数のAPIを提供しています。APIを利用することで、SendGridをアプリケーションの一機能として組み込むことが可能です。
今回は、Webアプリケーションとの親和性が高いHTTPベースのAPIである「Web API v3」について概要をご紹介します。

Web APIでできること

Web APIでは、SendGridダッシュボード上の機能をほぼ全て利用できます。全てを列挙はしませんが、以下のような種類があります。

• メール送信
  • Mail Send（メール送信）
  • Scheduled Sends（配信予約の設定やキャンセル）
• アカウント設定
  • API Keys（APIキーの作成や更新等）
  • Teammates（Teammateの作成や更新等）
  • Alerts（アラート設定）
  • Event Webhook（Event Webhookの設定）
  • など
• メール設定
  • Domain Authentication（独自ドメイン利用設定）
  • Tracking（メールトラッキング設定）
  • IP Management（送信元IPアドレスの管理。Proプランのみ）
  • など
• 統計情報取得
  • Global Stats（全体の統計情報の取得）
  • Category Stats（カテゴリ別の統計情報の取得）
  • など
• リスト管理
  • Bounces（バウンスリスト管理）
  • Blocks（ブロックリスト管理）
  • Spam Reports（迷惑メール報告リスト管理）
  • Invalid Emails（無効メールリスト管理）
  • Unsubscribes（配信停止リスト管理）
• マーケティングキャンペーン機能
  • Campaigns（キャンペーンの作成や送信）
  • Contacts（宛先リスト管理）
  • Sender Identities（送信元の管理）

インターフェースの概要

これらはJSONをサポートしたRESTfulなAPIです。基本的に、情報の取得系処理にGET、作成系処理にPOST、更新系処理にPATCHやPUTを利用します。

認証は、ダッシュボードで作成できるAPIキーを各APIコール時に付加することで行います。具体的にはAuthorizationヘッダに「Bearer YOUR_API_KEY」と指定します（YOUR_API_KEYは作成した実際のAPIキーに置き換えてください）。
また、作成・更新系のAPIをコールする際にはContent-Typeヘッダにapplication/jsonを指定する必要があります。

以下に、Mail Send APIを用いてシンプルなメールを送信するHTTPリクエストの例を記載します。

POST https://api.sendgrid.com/v3/mail/send HTTP/1.1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "personalizations": [
    {
      "to": [
        {
          "email": "john@example.com"
        }
      ],
      "subject": "Hello, World!"
    }
  ],
  "from": {
    "email": "from_address@example.com"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "Hello, World!"
    }
  ]
}

同じリクエストをcURLコマンドで行うと以下のようになります。

curl --request POST \
--url https://api.sendgrid.com/v3/mail/send \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "personalizations": [
    {
      "to": [
        {
          "email": "john@example.com"
        }
      ],
      "subject": "Hello, World!"
    }
  ],
  "from": {
    "email": "from_address@example.com"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "Hello, World!"
    }
  ]
}'

その他、全てのAPIのリクエストとレスポンスの例はAPIリファレンスをご覧ください。

• 日本語版APIリファレンス
• 英語版APIリファレンス

APIを試してみる

Google Chromeの拡張機能を用い、GUIベースで手軽にAPIを試す方法を以下のブログ記事で紹介しているのでご活用ください。

• ブラウザでWeb APIをテストする方法
• ブラウザでWeb APIをテストする方法　その２

APIライブラリの利用

SendGridのAPIを各プログラム言語から使用する場合、直接HTTPのリクエストを送信することもできますが、各言語向けのライブラリを使うことでより簡単にAPIを利用することができます。APIライブラリは公式およびコミュニティベースのものが多数公開されています。詳しくは「APIライブラリのご紹介」をご覧ください。
公式ライブラリについては、各言語ごとにサンプルを交えながら使用方法を解説したチュートリアルシリーズ記事もご覧ください。