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 Number 一度に取得するドメイン数。 デフォルト値 50。
Example: 50
offset No Number オフセット。 デフォルト値 0。
Example: 0
exclude_subusers No boolean 結果からサブユーザのドメインを除外します。 デフォルト値 "false"。
Example: true
username No string 指定したユーザに割り当てらてているDomain Whitelabel設定を検索します。
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設定の作成
Body引数 必須 条件 説明
domain Yes string Whitelabel設定するドメイン名.
Example: example.com
subdomain Yes string Whitelabel設定するサブドメイン名.
Example: news
automatic_security No boolean 自動セキュリティ設定。SendGridにSPFレコード、DKIMキー、DKIMキーローテーションの管理を許可するか否かを指定します.
Example: false
custom_spf No boolean カスタムSPF(ユーザがSPFレコードを管理)もしくはSendGridがSPF設定を管理するかを指定します. この設定は手動セキュリティの場合のみ有効です.
Example: true
default No boolean 送信者のドメイン名がDomain Whitelabel設定のドメインと一致しない場合にデフォルトWhitelabelとして使用するか否かを指定します.
Example: false

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引数 必須 条件 説明
id Yes number Domain Whitelabel設定のID
Example: 1234

Request

1

GET https://api.sendgrid.com/v3/whitelabel/domains/{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引数 必須 条件 説明
id Yes number 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/{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引数 必須 条件 説明
id Yes number Domain Whitelabel設定のID
Example: 1234

Request

1

DELETE https://api.sendgrid.com/v3/whitelabel/domains/{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 number 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 int 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 int 確認を実施する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_resuts": {
    "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
    }
  }
}
URI引数 必須 条件 説明
id Yes int 確認を実施する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

HTTP/1.1 500
{
  "errors": [
    {
      "message": "internal error getting TXT"
    }
  ]
}
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: jane@example.com

Request

1

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

{
  "username": "jane@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
    }
  }
}