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"
        },
        "to": { "$ref": "#/definitions/mailbox-list" },
        "cc": { "$ref": "#/definitions/mailbox-list" },
        "bcc": { "$ref": "#/definitions/mailbox-list" },
        "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 形式)

Sender と From について もあわせて参照してください。

.arguments.sender

string

メール送信者(RFC 5322 mailbox 形式)

Sender と From について もあわせて参照してください。

.arguments.to

[]string

To 送信先のリスト( RFC 5322 mailbox 形式)

.arguments.cc

[]string

Cc 送信先のリスト( RFC 5322 mailbox 形式)

.arguments.bcc

[]string

Bcc 送信先のリスト( RFC 5322 mailbox 形式)

.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 に単一のメール作成者を指定することを推奨します。