Domain Authentication

Domain Authenticationはサブドメインとドメインから構成されます。これらは、DKIM、SPF、Return-Pathの設定に使用されます。 また、SendGridがセキュリティの管理（自動セキュリティ）を行う、もしくはユーザ自身が管理を行う（手動セキュリティ）、いずれかのオプションがあります。手動セキュリティを利用する場合、ユーザは自身が管理するDNSにMX、DKIM、SPFなどのレコードを登録する必要があります。自動セキュリティを利用する場合、ユーザはSendGridの設定を指し示すCNAMEレコードを幾つか登録するだけで済みます。この場合、MX、DKIM、SPF、レコードはSendGrid側で管理します。

List all authenticated domains [GET]

Domain Authenticationの設定一覧取得
URI引数 必須 条件 説明
limit No integer 一度に取得するドメイン数。
Example: 50
offset No integer オフセット。
Example: 0
exclude_subusers No boolean 結果からサブユーザのドメインを除外します。
Example: true
username No string 指定したユーザに割り当てられているDomain Authenticationを検索します。
※構造計画研究所のマイページID（旧ユーザ名）ではなくSendGridアカウントのUsernameを指定してください。
Example: john
domain No string 指定したドメインにマッチするDomain Authenticationを検索します。
Example: example.com

Request

1

GET https://api.sendgrid.com/v3/whitelabel/domains?exclude_subusers={exclude_subusers}&limit={limit}&offset={offset}&username={username}&domain={domain} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

HTTP/1.1 200
[
  {
    "id": 1,
    "domain": "example.com",
    "subdomain": "mail",
    "username": "john@example.com",
    "user_id": 7,
    "ips": [
      "192.168.1.1",
      "192.168.1.2"
    ],
    "custom_spf": true,
    "default": true,
    "legacy": false,
    "automatic_security": true,
    "valid": true,
    "dns": {
      "mail_cname": {
        "host": "mail.example.com",
        "type": "cname",
        "data": "u7.wl.sendgrid.net",
        "valid": true
      },
      "spf": {
        "host": "example.com",
        "type": "txt",
        "data": "v=spf1 include:u7.wl.sendgrid.net -all",
        "valid": true
      },
      "dkim1": {
        "host": "s1._domainkey.example.com",
        "type": "cname",
        "data": "s1._domainkey.u7.wl.sendgrid.net",
        "valid": true
      },
      "dkim2": {
        "host": "s2._domainkey.example.com",
        "type": "cname",
        "data": "s2._domainkey.u7.wl.sendgrid.net",
        "valid": true
      }
    }
  },
  {
    "id": 2,
    "domain": "example2.com",
    "subdomain": "news",
    "username": "jane@example2.com",
    "user_id": 8,
    "ips": [

    ],
    "custom_spf": false,
    "default": true,
    "legacy": false,
    "automatic_security": true,
    "valid": false,
    "dns": {
      "mail_server": {
        "host": "news.example2.com",
        "type": "mx",
        "data": "sendgrid.net",
        "valid": false
      },
      "subdomain_spf": {
        "host": "news.example2.com",
        "type": "txt",
        "data": "v=spf1 include:sendgrid.net ~all",
        "valid": false
      },
      "domain_spf": {
        "host": "example2.com",
        "type": "txt",
        "data": "v=spf1 include:news.example2.com -all",
        "valid": false
      },
      "dkim": {
        "host": "s1._domainkey.example2.com",
        "type": "txt",
        "data": "k=rsa; t=s; p=publicKey",
        "valid": false
      }
    }
  }
]

Authenticate a domain [POST]

Domain Authenticationの作成

サブユーザのDomain Authenticationを作成する方法は以下の2通りあります。

1．親アカウントがusernameパラメータを指定してサブユーザの代わりにドメインを認証します。サブユーザは設定の確認や編集ができます。

2．親アカウントのDomain Authenticationをサブユーザに割り当てます。割り当てられたドメインがデフォルトとして利用されますが、サブユーザはそのドメインの確認や編集はできません。サブユーザ自身がドメイン認証設定を行うと、そちらの設定が優先されます。

設定の優先順位についてはこちらをご確認ください。

Domain Authenticationは最大3000まで作成可能です。

Body引数 必須 条件 説明
domain Yes string 対象のドメイン名.
Example: example.com
subdomain No string Return-Pathに付加するサブドメイン名.
Example: news
username No string Domain Authenticationを割り当てるサブユーザ名.
Example: subuser
ips No string[array] カスタムSPF（ユーザがSPFレコードを管理）のレコードに含まれるIPアドレス.
Example: 192.168.1.1
custom_spf No boolean カスタムSPFもしくはSendGridがSPF設定を管理するかを指定します。 この設定は手動セキュリティの場合のみ有効です.
Example: true
default No boolean 送信者のドメイン名がDomain Authenticationのドメインと一致しない場合にデフォルトの設定として使用するか否かを指定します.
Example: false
automatic_security No boolean 自動セキュリティ設定。SendGridにSPFレコード、DKIMキー、DKIMキーローテーションの管理を許可するか否かを指定します.
Example: false
custom_dkim_selector No string カスタムDKIMセレクタを指定します。 3桁の文字列または数字が利用できます.
Example: 001

Request

1

POST https://api.sendgrid.com/v3/whitelabel/domains HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12

{
  "domain": "example.com",
  "subdomain": "news",
  "username": "john@example.com",
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "custom_spf": true,
  "default": true,
  "automatic_security": false
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

HTTP/1.1 201
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "custom_spf": true,
  "default": true,
  "legacy": false,
  "automatic_security": true,
  "valid": true,
  "dns": {
    "mail_cname": {
      "host": "mail.example.com",
      "type": "cname",
      "data": "u7.wl.sendgrid.net",
      "valid": true
    },
    "spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:u7.wl.sendgrid.net -all",
      "valid": true
    },
    "dkim1": {
      "host": "s1._domainkey.example.com",
      "type": "cname",
      "data": "s1._domainkey.u7.wl.sendgrid.net",
      "valid": true
    },
    "dkim2": {
      "host": "s2._domainkey.example.com",
      "type": "cname",
      "data": "s2._domainkey.u7.wl.sendgrid.net",
      "valid": true
    }
  }
}

Retrieve an authenticated domain [GET]

Domain Authenticationの取得
URI引数 必須 条件 説明
domain_id Yes string Domain AuthenticationのID
Example: 1234

Request

1

GET https://api.sendgrid.com/v3/whitelabel/domains/{domain_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "custom_spf": true,
  "default": true,
  "legacy": false,
  "automatic_security": true,
  "valid": true,
  "dns": {
    "mail_cname": {
      "host": "mail.example.com",
      "type": "cname",
      "data": "u7.wl.sendgrid.net",
      "valid": true
    },
    "spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:u7.wl.sendgrid.net -all",
      "valid": true
    },
    "dkim1": {
      "host": "s1._domainkey.example.com",
      "type": "cname",
      "data": "s1._domainkey.u7.wl.sendgrid.net",
      "valid": true
    },
    "dkim2": {
      "host": "s2._domainkey.example.com",
      "type": "cname",
      "data": "s2._domainkey.u7.wl.sendgrid.net",
      "valid": true
    }
  }
}

Update an authenticated domain [PATCH]

Domain Authenticationの更新
URI引数 必須 条件 説明
domain_id Yes string Domain AuthenticationのID
Example: 1234
Body引数 必須 条件 説明
default No boolean デフォルトで使用するDomain Authenticationを意味します。 デフォルト値 false.
Example: false
custom_spf No boolean 手動セキュリティ用のカスタムSPFレコードを生成するか否かを示します。 デフォルト値 false.
Example: false

Request

1

PATCH https://api.sendgrid.com/v3/whitelabel/domains/{domain_id} HTTP/1.1
Request Body
1
2
3
4

{
  "default": false,
  "custom_spf": true
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Delete an authenticated domain [DELETE]

Domain Authenticationの削除
URI引数 必須 条件 説明
domain_id Yes string Domain AuthenticationのID
Example: 1234

Request

1

DELETE https://api.sendgrid.com/v3/whitelabel/domains/{domain_id} HTTP/1.1

Response

1

HTTP/1.1 204

Get the default authentication [GET]

デフォルトDomain Authenticationの取得
URI引数 必須 条件 説明
domain No string Domain Authenticationのドメインに対応する送信ドメイン.
Example: em.example.com

Request

1

GET https://api.sendgrid.com/v3/whitelabel/domains/default?domain={domain} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [
    "192.168.1.1"
  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Add an IP to an authenticated domain [POST]

Domain AuthenticationへのIPアドレスの追加
URI引数 必須 条件 説明
id Yes integer IPアドレスを追加するDomain AuthenticationのID.
Example: 1234
Body引数 必須 条件 説明
ip Yes string Domain Authenticationに関連付けるIPアドレス. カスタムSPFでIPアドレスを直接指定する場合に使用されます.
Example: 192.168.0.1

Request

1

POST https://api.sendgrid.com/v3/whitelabel/domains/{id}/ips HTTP/1.1
Request Body
1
2
3

{
  "ip": "192.168.0.1"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "john@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Remove an IP from an authenticated domain [DELETE]

Domain AuthenticationからのIPアドレスの削除
URI引数 必須 条件 説明
id Yes integer IPアドレスを削除するDomain AuthenticationのID.
Example: 1234
ip Yes string Domain Authenticationから削除するIPアドレス.
Example: 127.0.0.1

Request

1

DELETE https://api.sendgrid.com/v3/whitelabel/domains/{id}/ips/{ip} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "mail@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Validate a domain authentication [POST]

Domain Authenticationの検証

設定したドメインの検証を行うことができます。検証に失敗した場合は、その理由がエラーメッセージとして返されます。

URI引数 必須 条件 説明
id Yes integer 検証したいDomain AuthenticationのID.
Example: 1234

Request

1

POST https://api.sendgrid.com/v3/whitelabel/domains/{id}/validate HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

HTTP/1.1 200
{
  "id": 1,
  "valid": true,
  "validation_results": {
    "mail_cname": {
      "valid": false,
      "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"."
    },
    "dkim1": {
      "valid": true,
      "reason": null
    },
    "dkim2": {
      "valid": true,
      "reason": null
    },
    "spf": {
      "valid": true,
      "reason": null
    }
  }
}
Domain Authenticationは親アカウントの権限でサブユーザに割り当てることができます。この機能を利用することにより、サブユーザは親アカウントの設定を利用してメール送信することができます。設定を割り当てるためには、はじめに親アカウントでDomain Authenticationの設定を作成してValidateを通す必要があります。その後、親アカウントの権限でSubuser Management機能を使用してサブユーザに割り当てます。

List the authenticated domains associated with a subuser [GET]

関連するDomain Authenticationの一覧取得
URI引数 必須 条件 説明
username Yes string Domain Authenticationに割り当てられているサブユーザのユーザ名.

Request

1

GET https://api.sendgrid.com/v3/whitelabel/domains/subuser?username={username} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

HTTP/1.1 200
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "mail@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}

Disassociate an authenticated domain from a subuser [DELETE]

Domain Authenticationの割り当て解除
URI引数 必須 条件 説明
username Yes string Domain Authenticationに割り当てられているサブユーザのユーザ名.

Request

1

DELETE https://api.sendgrid.com/v3/whitelabel/domains/subuser HTTP/1.1

Response

1

HTTP/1.1 204

Associate an authenticated domain with a subuser [POST]

Domain Authenticationの割り当て
URI引数 必須 条件 説明
domain_id Yes integer サブユーザに割り当てるDomain AuthenticationのID.
Example: 1234
Body引数 必須 条件 説明
username Yes string Domain Authenticationと関連付けるサブユーザのユーザ名.
Example: janeexampexample@example.com

Request

1

POST https://api.sendgrid.com/v3/whitelabel/domains/{domain_id}/subuser HTTP/1.1
Request Body
1
2
3

{
  "username": "janeexampexample@example.com"
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

HTTP/1.1 201
{
  "id": 1,
  "domain": "example.com",
  "subdomain": "mail",
  "username": "mail@example.com",
  "user_id": 7,
  "ips": [

  ],
  "custom_spf": true,
  "default": false,
  "legacy": false,
  "automatic_security": false,
  "valid": false,
  "dns": {
    "mail_server": {
      "host": "mail.example.com",
      "type": "mx",
      "data": "sendgrid.net",
      "valid": false
    },
    "subdomain_spf": {
      "host": "mail.example.com",
      "type": "txt",
      "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all",
      "valid": false
    },
    "domain_spf": {
      "host": "example.com",
      "type": "txt",
      "data": "v=spf1 include:mail.example.com -all",
      "valid": false
    },
    "dkim": {
      "host": "s1._domainkey.example.com",
      "type": "txt",
      "data": "k=rsa; t=s; p=publicKey",
      "valid": false
    }
  }
}