Gehirn MTA¶

このドキュメントでは Gehirn MTA が提供する API のご利用方法を説明します。

Gehirn MTA の API ドキュメントは OpenAPI 形式でも提供しています。

メッセージ送信¶

HTTP リクエスト¶

POST /mta/v1/tasks?is_sync=true HTTP/1.1
Host: api.gis.gehirn.jp
Content-Type: application/json

リクエストボディ¶

{
  "definitions": {
    "mailbox-list": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      },
      "mimItems": 1
    }
  },
  "type": "object",
  "required": [
    "procedure",
    "arguments"
  ],
  "properties": {
    "procedure": {
      "const": "send_message"
    },
    "arguments": {
      "type": "object",
      "required": [
        "self",
        "subject",
        "content_type",
        "body"
      ],
      "properties": {
        "self": {
          "type": "string",
          "pattern": "^https://api\\.gis\\.gehirn\\.jp/mta/v1/domains/[^/]+$"
        },
        "from": { "$ref": "#/definitions/mailbox-list" },
        "sender": {
          "type": "string",
          "format": "email"
        },
        "reply_to": { "$ref": "#/definitions/mailbox-list" },
        "to": { "$ref": "#/definitions/mailbox-list" },
        "cc": { "$ref": "#/definitions/mailbox-list" },
        "bcc": { "$ref": "#/definitions/mailbox-list" },
        "message_id": {
          "type": "string"
        },
        "in_reply_to": {
          "type": "array",
          "items": { "type": "string" }
        },
        "references": {
          "type": "array",
          "items": { "type": "string" }
        },
        "subject": {
          "type": "string"
        },
        "content_type": {
          "type": "string",
          "oneOf": [
            { "pattern": "^text/.*$" },
            { "pattern": "^multipart/.*$" }
          ]
        },
        "additional_header": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "body": {
          "type": "string"
        },
        "attachments": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "content_type",
              "content"
            ],
            "properties": {
              "filename": {
                "type": "string"
              },
              "content_type": {
                "type": "string",
                "minLength": 1
              },
              "content": {
                "type": "string",
                "contentEncoding": "base64"
              }
            }
          },
          "mimItems": 0
        }
      },
      "allOf": [
        {
          "anyOf": [
            { "required": [ "to" ] },
            { "required": [ "cc" ] },
            { "required": [ "bcc" ] }
          ]
        },
        {
          "anyOf": [
            {
              "required": [ "sender" ]
            },
            {
              "properties": {
                "from": { "maxItems": 1 }
              },
              "required": [ "from" ]
            }
          ]
        }
      ]
    }
  }
}

リクエストプロパティ¶
プロパティ	型	説明
.procedure	string	`send_message` 固定
.arguments.self	string	メール送信元 Gehirn MTA ドメインの URL `https://api.gis.gehirn.jp/mta/v1/domains/:domain_id`
.arguments.from	[]string	メール作成者のリスト（ RFC 5322 mailbox-list 形式） Sender と From についてもあわせて参照してください。
.arguments.sender	string	メール送信者（RFC 5322 mailbox 形式） Sender と From についてもあわせて参照してください。
.arguments.reply_to	[]string	このメールへの返信を受け取る返信先のリスト ( RFC 5322 mailbox-list 形式)
.arguments.to	[]string	To 送信先のリスト（ RFC 5322 mailbox-list 形式）
.arguments.cc	[]string	Cc 送信先のリスト（ RFC 5322 mailbox-list 形式）
.arguments.bcc	[]string	Bcc 送信先のリスト（ RFC 5322 mailbox-list 形式）
.arguments.message_id	string	このメールを一意に特定する ID
.arguments.in_reply_to	[]string	返信先のメールの Message-ID メールスレッドの指定もあわせて参照してください。
.arguments.references	[]string	このメールに関連するメール (スレッド) の Message-ID メールスレッドの指定もあわせて参照してください。
.arguments.subject	string	メールサブジェクト (UTF-8)
.arguments.content_type	string	メール本文の Content-Type text/* multipart/*
.arguments.additional_header	object<string, []string>	追加のヘッダーフィールド。任意の RFC 5322 optional-field を指定できますが、一部のフィールドは Gehirn MTA により上書きされる場合があります。フィールドネームを含む 1 行の長さが MIME の制限 998 オクテットを超える場合は適宜 RFC 5322 FWS を挿入してください。 `obs-unstruct` 及び `obs-FWS` は利用できません。
.arguments.body	string	メール本文改行コードは `CRLF` に正規化されます。 `.arguments.content_type` が text/* の場合は自動的に Content-Transfer-Encoding の変換が行われます。また `.arguments.attachments` の指定がある場合は自動的に `multipart/mixed` 形式に変換されます。有効な UTF-8 の文字列を指定してください。 `.arguments.content_type` が multipart/* の場合は改行コードの正規化を除き、自動的な変換は行われません。事前に必要な変換を施した ASCII 文字列を指定してください。
.arguments.attacuments[]	[]object	添付ファイルのリスト `.arguments.content_type` がtext/* のときのみ使用できます。 multipart/* の場合は .arguments.body に直接エンコーディングしてください。
.arguments.attacuments[].filename	string	添付ファイルのファイル名
.arguments.attacuments[].content_type	string	添付ファイルの Content-Type
.arguments.attacuments[].content	string	添付ファイル (Base64)

コード例¶

text/plain¶

#!/bin/bash
set -eu

GEHIRN_API_STATIC_TOKEN_ID=""
GEHIRN_API_STATIC_TOKEN_SECRET=""
GEHIRN_MTA_DOMAIN_URL="https://api.gis.gehirn.jp/mta/v1/domains/:domain_id"

FROM="from@example.jp"
TO="to@example.net"

curl \
    --user "$GEHIRN_API_STATIC_TOKEN_ID:$GEHIRN_API_STATIC_TOKEN_SECRET" \
    -H 'Content-Type: application/json' \
    https://api.gis.gehirn.jp/mta/v1/tasks\?is_sync\=true \
    --data-binary @<(jq \
      -nf /dev/stdin \
      --arg self "$GEHIRN_MTA_DOMAIN_URL" \
      --arg from "$FROM" \
      --arg to "$TO" \
      --arg subject "メール送信のテスト" \
      --arg cty "text/plain; charset=UTF-8" \
      --arg body "本文" \
      --arg attachment "$(base64 -w0 attachment.png)" \
      << 'EOF'
{
  "procedure": "send_message",
  "arguments": {
    "self": $self,
    "from": [$from],
    "to": [$to],
    "subject": $subject,
    "content_type": $cty,
    "additional_header": {
      "Auto-Submitted": ["auto-generated"]
    },
    "body": $body,
    "attachments": [
      {
        "filename": "attachment.png",
        "content_type": "image/png",
        "content": $attachment
      }
    ]
  }
}
EOF
)

multipart/alternative¶

#!/bin/bash
set -eu

GEHIRN_API_STATIC_TOKEN_ID=""
GEHIRN_API_STATIC_TOKEN_SECRET=""
GEHIRN_MTA_DOMAIN_URL="https://api.gis.gehirn.jp/mta/v1/domains/:domain_id"

FROM="from@example.jp"
TO="to@example.net"

BODY='--randomboundary
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hello, World
--randomboundary
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<html><head></head><body>Hello, World</body></html>
--randomboundary--'

curl \
    --user "$GEHIRN_API_STATIC_TOKEN_ID:$GEHIRN_API_STATIC_TOKEN_SECRET" \
    -H 'Content-Type: application/json' \
    https://api.gis.gehirn.jp/mta/v1/tasks\?is_sync\=true \
    --data-binary @<(jq \
      -nf /dev/stdin \
      --arg self "$GEHIRN_MTA_DOMAIN_URL" \
      --arg from "$FROM" \
      --arg to "$TO" \
      --arg subject "マルチパートメールのテスト" \
      --arg cty 'multipart/alternative; boundary="randomboundary"' \
      --arg body "$BODY" \
      << 'EOF'
{
  "procedure": "send_message",
  "arguments": {
    "self": $self,
    "from": [$from],
    "to": [$to],
    "subject": $subject,
    "content_type": $cty,
    "additional_header": {
      "Auto-Submitted": ["auto-generated"],
      "Content-Transfer-Encoding": ["7bit"],
    },
    "body": $body
  }
}
EOF
)

Sender と From について¶

RFC 5322 ではメールの作成者を示す From を連名で複数指定することが許されています。このとき、実際に送信を担当した人またはシステムを Sender として示すことが求められています。

このため、 Gehirn MTA のメッセージ送信 API では次の条件を満たすことを求めています。

.arguments.from[] にメール作成者がひとつのみ指定されている
または .arguments.sender に有効なメール送信者が指定されている
- このとき .arguments.from[] にメール作成者を複数指定することが許可されます

ただし、送信元認証メカニズムのひとつである DMARC では、 From に複数のメール作成者が指定された場合の取り扱い方法を定めていません。このため、 From に複数のメール作成者を指定した場合は、 DMARC の設定内容によってはメール送信先で受け取りを拒否されたり検疫されたりする場合があります。

したがって、現在では From に単一のメール作成者を指定することを推奨します。

メールスレッドの指定¶

In-Reply-To フィールドと References フィールドはともに関連するメール (スレッド) を参照するためのフィールドですが、使用方法が異なります。

ここで簡単にご説明いたします。より詳しくは RFC 5322 を参照してください。

In-Reply-To¶

In-Reply-To フィールドには、そのメールが返信する直接の親にあたるメールの Message-ID を指定します。親が Message-ID を持たない場合は指定しません。

References¶

一方、 References フィールドには親に加え祖先 (親の親、さらにその親) にあたるメールの Message-ID を指定します。

References フィールドの値は、標準的には以下のようにして組み立てます。

値を空文字列で初期化します
以下のいずれかの手順により、祖先を指定します
- 親メールが References を含む場合、その値を使用します
- 親メールが References を含まずに In-Reply-To を含み、かつその内容が単独の親を参照する場合、その値を使用します
- これ以外の場合はなにもしません
親メールが Message-ID を含む場合、その値を追加します

この手順を返信を作成するたびに繰り返すことで、すべての関連するメールを References フィールドで参照することができます。

Gmail におけるスレッド¶

Gmail では送信者や受信者、件名に応じたメールのスレッド化が行われますが、References フィールドにより明示的にスレッドを制御することができます。 Gehirn MTA から送信するメールが正しくスレッド化されたり、反対に同じ件名でもスレッド化を解除したいときには References フィールドをご指定ください。

詳しくは Threading changes in Gmail conversation view をご参照ください。