Skip to content Skip to navigation Skip to topbar

On this page

Automate Adding Subusers with the SendGrid API

You can utilize the SendGrid API to automate the addition of Subusers to your account. Use the following curl examples to add a Subuser using the SendGrid V3.0 API.

Prerequisites for automating addition of Subusers to your account

Before you can start using the API, you need to do the following:

Create a SendGrid account.
Create an API Key.
Make sure you have curl installed on your machine.

(information)

Info

cURL comes standard on Mac operating systems.

How to add a Subuser via the SendGrid API and curl

Creating the Subuser

Create Subuser - Creating the actual account, the profile, username, password, and the keys you want on the account.

1curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
2  "username": “examplecurltesting",
3  "email": "example@example.com",
4  "password": “PASSWORD",
5  "ips": [
6  "167.89.38.39",
7  "198.37.152.144"
8  ]
9}' 'https://api.sendgrid.com/v3/subusers'

The successful Response looks like this:

1=> 2xx
2{
3  "username": "examplecurltesting",
4  "user_id": 1868534,
5  "email": "example@example.com",
6  "signup_session_token": "",
7  "authorization_token": "",
8  "credit_allocation": { "type": "unlimited" }
9}

GET Subusers (optional step to confirm POST):

curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/subusers'

Response:

1[
2  { "disabled": false, "email": "example@example.com", "id": 1762958, "username": "exampletestingv3subuserapi" },
3  { "disabled": false, "email": "example@testsite.com", "id": 1766771, "username": "examplesubuser-UI" },
4  { "disabled": false, "email": "example@testsite.com", "id": 1803837, "username": "exampleisasubuser" },
5  { "disabled": false, "email": "example@example.com", "id": 1868534, "username": "examplecurltesting" }
6]

Create API Keys (optional, depends on integration style): If the application would rather run on API keys than a password, then follow this step:

curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"name": “API KEY NAME"}' 'https://api.sendgrid.com/v3/api_keys'

or, you can create the key for your Subuser:

1curl -X POST -H "Authorization: Bearer PARENT_APIKEY_HERE"
2  -H "On-Behalf-Of: examplecurltesting" \
3  -H "Content-Type: application/json" -d '{"name": “API KEY NAME"}' \
4  'https://api.sendgrid.com/v3/api_keys'

Successful API key implementation Response:

1=> 201 created
2{
3  "api_key": "SG.XXXXXXXXXXXXXXXXXXXXXXXXX",
4  "api_key_id": "sample_id",
5  "name": "new api key",
6  "scope_set_id": "00766089-9730-4f16-8191-b8bedc5f57f5"
7}

Once this has been done, the Subuser has been created. From this point on, we'll cover implementing Click Tracking, Open Tracking, and the Event Webhook for those Subusers.

Enable/Edit Applications

As of right, now this needs to be done directly through the account in question.

Click Tracking

curl -X PATCH -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"enabled": true,"enable_text" : true}' 'https://api.sendgrid.com/v3/tracking_settings/click'

Response:

1=> 200 OK
2{ "enable_text": true, "enabled": true }

Open Tracking

curl -X PATCH -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"enabled": true}' 'https://api.sendgrid.com/v3/tracking_settings/open'

Response:

1=> 200 ok
2{ "enabled": true }

Event Webhook

curl -X PATCH -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"enabled": true,"url":"https://api.keen.io/3.0/projects/526a8a5f05cd660472000012/partners/sendgrid?api_key=081da3fc30ca5b11b1f8b133de7064817b57c86d3261f140dc36243eb6829a100d4c5e38db8dd289194d4e02159bbf7ebad74a1fba1fce7a421a00c7a2f7d0f8ba5ef6ea3cece6345904d79395c35cdeaed221c3a208c897e79dd95da399a1d2d1d3e66768af929aa52d621e5bd296a5","group_resubscribe": true,"delivered": true,"group_unsubscribe": true,"bounce": true,"deferred": true,"unsubscribe": true,"processed": true,"open": true,"click": true,"dropped": true}' 'https://api.sendgrid.com/v3/user/webhooks/event/settings'

Response:

1=> 200 ok
2{
3    "bounce": true,
4    "click": true,
5    "deferred": true,
6    "delivered": true,
7    "dropped": true,
8    "enabled": true,
9    "group_resubscribe": true,
10    "group_unsubscribe": true,
11    "open": true,
12    "processed": true,
13    "spam_report": false,
14    "unsubscribe": true,
15    "url": "https://api.keen.io/3.0/projects/526a8a5f05cd660472000012/partners/sendgrid?api_key=081da3fc30ca5b11b1f8b133de7064817b57c86d3261f140dc36243eb6829a100d4c5e38db8dd289194d4e02159bbf7ebad74a1fba1fce7a421a00c7a2f7d0f8ba5ef6ea3cece6345904d79395c35cdeaed221c3a208c897e79dd95da399a1d2d1d3e66768af929aa52d621e5bd296a5"
16}

Domain Authentication for the Subuser

Now we are going to setup Domain Authentication for the Subusers created above. This process involves creating the parent Domain Authentication and then associating it with your Subusers:

Create Domain Authentication

1curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
2  "domain": "example.com",
3  "subdomain": "subdomain",
4  "ips": [
5  "167.89.38.39",
6  "198.37.152.144"
7  ],
8  "default": true,
9  "automatic_security": true
10  }' 'https://api.sendgrid.com/v3/whitelabel/domains'

Response:

1=> 2xx
2{
3  "id": 50784,
4  "user_id": 624781,
5  "subdomain": "subdomain",
6  "domain": "example.com",
7  "username": "examplecurltesting",
8  "ips": ["167.89.38.39", "198.37.152.144"],
9  "custom_spf": false,
10  "default": true,
11  "legacy": false,
12  "automatic_security": true,
13  "valid": false,
14  "dns": {
15    "mail_cname": {
16      "valid": false,
17      "type": "cname",
18      "host": "subdomain.example.com",
19      "data": "u624781.wl.sendgrid.net"
20    },
21    "dkim1": {
22      "valid": false,
23      "type": "cname",
24      "host": "s1._domainkey.example.com",
25      "data": "s1.domainkey.u624781.wl.sendgrid.net"
26    },
27    "dkim2": {
28      "valid": false,
29      "type": "cname",
30      "host": "s2._domainkey.example.com",
31      "data": "s2.domainkey.u624781.wl.sendgrid.net"
32    },
33    "spf": {
34      "valid": false,
35      "type": "txt",
36      "host": "example.com",
37      "data": "v=spf1 include:u624781.wl.sendgrid.net -all"
38    }
39  }
40}

You will want to look for the Domain Authentication ID here (in this example, the ID is "id": 50784), as this will be used in the next calls to append this ID to the Subusers. Also, the records needed to validate this Domain Authentication will be passed back in the response.

Create Reverse DNS

1curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: application/json” -d '{"ip": "167.89.66.50",
2  "subdomain": "email",
3  "domain": "example.com"}' 'https://api.sendgrid.com/v3/whitelabel/ips'

Successful Response:

1 => 2xx
2{
3  "id": 11887,
4  "ip": "167.89.66.50",
5  "rdns": "o4.email.example.com",
6  "users": [],
7  "subdomain": "email",
8  "domain": "example.com",
9  "a_record": {
10    "valid": false,
11    "type": "a",
12    "host": "o4.email.example.com",
13    "data": "167.89.66.50"
14  },
15  "valid": false,
16  "legacy": false
17}

Create Link Branding

1curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
2  "domain": "example.com",
3  "subdomain": "links",
4  "default": true
5  }' 'https://api.sendgrid.com/v3/whitelabel/links'

Response:

1=> 2xx
2{
3  "id": 42371,
4  "user_id": 624781,
5  "domain": "example.com",
6  "subdomain": "links",
7  "username": "examplecurltesting",
8  "valid": false,
9  "default": true,
10  "legacy": false,
11  "dns": {
12    "domain_cname": {
13      "valid": false,
14      "type": "cname",
15      "host": "links.example.com",
16      "data": "sendgrid.net"
17    },
18    "owner_cname": {
19      "valid": false,
20      "type": "cname",
21      "host": "624781.example.com",
22      "data": "sendgrid.net"
23    }
24  }
25}

After creating DNS records then wait for them to propagate and validate records.

GET all Domain Authentication IDs - grab the ID to validate and associate to an account.

curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains'

Response:

1= 2xx ok
2{
3  "id": 50784,
4  "user_id": 624781,
5  "subdomain": "subdomain",
6  "domain": "example.com",
7  "username": "examplecurltesting",
8  "ips": ["167.89.38.39", "198.37.152.144"],
9  "custom_spf": false,
10  "default": true,
11  "legacy": false,
12  "automatic_security": true,
13  "valid": false,
14  "dns": {
15    "mail_cname": {
16      "valid": false,
17      "type": "cname",
18      "host": "subdomain.example.com",
19      "data": "u624781.wl.sendgrid.net"
20    },
21    "dkim1": {
22      "valid": false,
23      "type": "cname",
24      "host": "s1._domainkey.example.com",
25      "data": "s1.domainkey.u624781.wl.sendgrid.net"
26    },
27    "dkim2": {
28      "valid": false,
29      "type": "cname",
30      "host": "s2._domainkey.example.com",
31      "data": "s2.domainkey.u624781.wl.sendgrid.net"
32    },
33    "spf": {
34      "valid": false,
35      "type": "txt",
36      "host": "example.com",
37      "data": "v=spf1 include:u624781.wl.sendgrid.net -all"
38    }
39  }
40}

Validate ID of the Domain Authentication Once you have the ID of the Domain Authentication you can Validate it.

curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains/50784/validate'

Response:

1=> 2xx
2{
3  "id": 50784,
4  "valid": true,
5  "validation_results": {
6    "mail_cname": {
7      "valid": false,
8      "reason": "Expected your MX record to be 'mx.sendgrid.net' but found 'example.com'."
9    },
10    "dkim1": { "valid": true, "reason": null },
11    "dkim2": { "valid": true, "reason": null },
12    "spf": { "valid": true, "reason": null }
13  }
14}

Associate with a Subuser Once Validated, you can associate to any Subuser accounts.

1curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
2"username": "examplecurltesting"
3}' 'https://api.sendgrid.com/v3/whitelabel/domains/50784/subuser'

Link Branding Follow the same process with Link branding:

1-> GET link ID (ex. 42371)
2curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -'https://api.sendgrid.com/v3/whitelabel/links'

Response:

1 => 200 ok
2[
3  {
4    "id": 203,
5    "user_id": 624781,
6    "domain": "example.com",
7    "subdomain": "links",
8    "username": "examplecurltesting",
9    "valid": true,
10    "default": false,
11    "legacy": false,
12    "dns": {
13      "domain_cname": {
14        "valid": true,
15        "type": "cname",
16        "host": "links.example.com",
17        "data": "sendgrid.net"
18      },
19      "owner_cname": {
20        "valid": true,
21        "type": "cname",
22        "host": "624781.example.com",
23        "data": "sendgrid.net"
24      }
25    }
26  },
27  {
28    "id": 202,
29    "user_id": 624781,
30    "domain": "example.org",
31    "subdomain": "links",
32    "username": "examplecurltesting",
33    "valid": true,
34    "default": false,
35    "legacy": false,
36    "dns": {
37      "domain_cname": {
38        "valid": true,
39        "type": "cname",
40        "host": "links.example.org",
41        "data": "sendgrid.net"
42      },
43      "owner_cname": {
44        "valid": true,
45        "type": "cname",
46        "host": "624781.example.org",
47        "data": "sendgrid.net"
48      }
49    }
50  },
51  {
52    "id": 42371,
53    "user_id": 624781,
54    "domain": "example.net",
55    "subdomain": "links",
56    "username": "examplecurltesting",
57    "valid": false,
58    "default": true,
59    "legacy": false,
60    "dns": {
61      "domain_cname": {
62        "valid": false,
63        "type": "cname",
64        "host": "links.example.net",
65        "data": "sendgrid.net"
66      },
67      "owner_cname": {
68        "valid": false,
69        "type": "cname",
70        "host": "624781.example.net",
71        "data": "sendgrid.net"
72      }
73    }
74  }
75]

Validate Link Branding:

curl -X POST -H "Authorization: Basic XXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/links/203/validate'

Response:

1=> 200 ok
2{
3  "id": 203,
4  "valid": true,
5  "validation_results": {
6    "domain_cname": {
7      "valid": true,
8      "reason": null
9    },
10    "owner_cname": {
11      "valid": true,
12      "reason": null
13    }
14  }
15}

Associate Link Branding:

curl -X POST -H "Authorization: Basic XXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"username": "jane@example.com”}' 'https://api.sendgrid.com/v3/whitelabel/links/{link_id}/subuser'

Response:

1=> 201 created
2{
3  "id": 200,
4  "user_id": 623032,
5  "domain": "example.com",
6  "subdomain": "links",
7  "username": "examplecurltesting",
8  "valid": false,
9  "default": false,
10  "legacy": false,
11  "dns": {
12    "domain_cname": {
13      "valid": false,
14      "type": "cname",
15      "host": "links.example.com",
16      "data": "sendgrid.net"
17    },
18    "owner_cname": {
19      "valid": true,
20      "type": "cname",
21      "host": "623032.example.com",
22      "data": "sendgrid.net"
23    }
24  }
25}

Next Steps

For more information on SendGrid and where you can go from here, check out these pages: