Domains

Domain Whitelabels

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

List all Domains [GET]

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

Create a Domain [POST]

Domain Whitelabel設定の作成

サブユーザの送信ドメイン認証設定を作成する方法は以下の2通りあります。

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

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

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

Domain Whitelabel設定は最大3000まで作成可能です。

Body引数 必須 条件 説明
domain Yes string 対象のドメイン名.
Example: example.com
subdomain No string Return-Pathに付加するサブドメイン名.
Example: news
username No string 送信ドメイン認証設定を割り当てるサブユーザ名.
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 Whitelabel設定のドメインと一致しない場合にデフォルトの設定として使用するか否かを指定します.
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 a Domain [GET]

Domain Whitelabel設定の取得
URI引数 必須 条件 説明
domain_id Yes string Domain Whitelabel設定の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 a Domain [PATCH]

Domain Whitelabel設定の更新
URI引数 必須 条件 説明
domain_id Yes string Domain Whitelabel設定のID
Example: 1234
Body引数 必須 条件 説明
default No boolean デフォルトで使用するDomain Whitelabel設定を意味します。 デフォルト値 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 a Domain [DELETE]

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

Request

1

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

Response

1

HTTP/1.1 204

Default Domain [GET]

デフォルトDomain Whitelabel設定の取得
URI引数 必須 条件 説明
domain No string Domain Whitelabel設定のドメインに対応する送信ドメイン.
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 a Domain [POST]

Domain Whitelabel設定へのIPアドレスの追加
URI引数 必須 条件 説明
id Yes integer IPアドレスを追加するDomain Whitelabel設定のID.
Example: 1234
Body引数 必須 条件 説明
ip Yes string Domain Whitelabel設定に関連付ける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 a Domain [DELETE]

Domain Whitelabel設定からのIPアドレスの削除
URI引数 必須 条件 説明
id Yes integer IPアドレスを削除するDomain Whitelabel設定のID.
Example: 1234
ip Yes string Domain Whitelabel設定から削除する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 Domain [POST]

Domain Whitelabel設定の検証

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

URI引数 必須 条件 説明
id Yes integer 検証したいDomain Whitelabel設定の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 Whitelabel設定は親アカウントの権限でサブユーザに割り当てることができます。 この機能を利用することにより、サブユーザは親アカウントのWhitelabel設定を利用してメール送信することができます。Whitelabel設定を割り当てるためには、はじめに親アカウントでDomain Whitelabel設定を作成してValidateを通す必要があります。その後、親アカウントの権限でSubuser Management機能を使用してサブユーザに割り当てます。

List Associated Domain [GET]

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

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 Domain [DELETE]

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

Request

1

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

Response

1

HTTP/1.1 204

Associate Domain [POST]

Domain Whitelabel設定の割り当て
URI引数 必須 条件 説明
domain_id Yes integer サブユーザに割り当てるDomain Whitelabel設定のID.
Example: 1234
Body引数 必須 条件 説明
username Yes string Domain Whitelabel設定と関連付けるサブユーザのユーザ名.
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
    }
  }
}