New page in For Developers: Automating Subusers

[apigirl]

Here is a series of cURL code examples that we have for automating adding subusers. The todo here is to validate these examples, and then following our styleguide, create a new page called "Automating Subusers" in For Developers > Sending Email > V3 API.

Step #1

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

curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
"username": “YOUR NEW SUBUSER USERNAME",
"email": “CONTACT EMAIL",
"password": “PASSWORD",
"ips": [
"167.89.38.39",
"198.37.152.144"
]
}' 'https://api.sendgrid.com/v3/subusers'

The successful Response looks like this: => 2xx
{"username”:”YOUR NEW SUBUSER NAME","user_id":1868534,"email”:”YOUR CONTACT EMAIL","signup_session_token":"","authorization_token":"","credit_allocation":{"type":"unlimited"}}

2. 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:
[{"disabled":false,"email":"example@gmail.com","id":1762958,"username":"exampletestingv3subuserapi"},{"disabled":false,"email":"example@sendgrid.com","id":1766771,"username":"examplesubuser-UI"},{"disabled":false,"email":"example@sendgrid.com","id":1803837,"username":"exampleisasubuser"},{"disabled":false,"email":"example@gmail.com","id":1868534,"username":"examplecurltesting"}]

3. Create API Keys (optional, depends on integration style): If the application would rather run on API keys rather than 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 Create the Key for your subuser:

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

Successful API key implementation Response =>
201 created
{"api_key":"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","api_key_id":"rGaWG-xBTHiBuhCLxWZ0Hg","name":"new api key","scope_set_id":"00766089-9730-4f16-8191-b8bedc5f57f5"}

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 acct in question)

4. 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 => 200 OK
{"enable_text":true,"enabled":true}

5. 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 => 200 ok
{"enabled":true}

6. Webhook - Event Notification App

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'

=> had to remove ‘spamreport’ in order to get this to work:
Kept receiving: {"errors":[{"message":"unknown field: "spamreports""}]}

Response=> 200 ok
{
"bounce": true,
"click": true,
"deferred": true,
"delivered": true,
"dropped": true,
"enabled": true,
"group_resubscribe": true,
"group_unsubscribe": true,
"open": true,
"processed": true,
"spam_report": false,
"unsubscribe": true,
"url": "https://api.keen.io/3.0/projects/526a8a5f05cd660472000012/partners/sendgrid?api_key=081da3fc30ca5b11b1f8b133de7064817b57c86d3261f140dc36243eb6829a100d4c5e38db8dd289194d4e02159bbf7ebad74a1fba1fce7a421a00c7a2f7d0f8ba5ef6ea3cece6345904d79395c35cdeaed221c3a208c897e79dd95da399a1d2d1d3e66768af929aa52d621e5bd296a5"}
Now we’re going to whitelabel the subusers created above. This process involves creating the parent whitelabel and then associating it with your subusers:

1. Create Domain Authentication
   curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
   "domain": "staples.com",
   "subdomain": "subdomain",
   "ips": [
   "167.89.38.39",
   "198.37.152.144"
   ],
   "default": true,
   "automatic_security": true
   }' 'https://api.sendgrid.com/v3/whitelabel/domains'

Successful Response => 2xx

{"id":50784,"user_id":624781,"subdomain":"subdomain","domain":"staples.com","username":"ryan.burrer","ips":["167.89.38.39","198.37.152.144"],"custom_spf":false,"default":true,"legacy":false,"automatic_security":true,"valid":false,
"dns":{"mail_cname":{"valid":false,"type":"cname","host":"subdomain.staples.com","data":"u624781.wl.sendgrid.net"},"dkim1":{"valid":false,"type":"cname","host":"s1._domainkey.staples.com","data":"s1.domainkey.u624781.wl.sendgrid.net"},"dkim2":{"valid":false,"type":"cname","host":"s2._domainkey.staples.com","data":"s2.domainkey.u624781.wl.sendgrid.net"},"spf":{"valid":false,"type":"txt","host":"staples.com","data":"v=spf1 include:u624781.wl.sendgrid.net -all"}}}
{
"id": 50784,
"user_id": 624781,
"subdomain": "subdomain",
"domain": "staples.com",
"username": "ryan.burrer",
"ips": [
"167.89.38.39",
"198.37.152.144"
],
"custom_spf": false,
"default": true,
"legacy": false,
"automatic_security": true,
"valid": false,
"dns": {
"mail_cname": {
"valid": false,
"type": "cname",
"host": "subdomain.staples.com",
"data": "u624781.wl.sendgrid.net"
},
"dkim1": {
"valid": false,
"type": "cname",
"host": "s1._domainkey.staples.com",
"data": "s1.domainkey.u624781.wl.sendgrid.net"
},
"dkim2": {
"valid": false,
"type": "cname",
"host": "s2._domainkey.staples.com",
"data": "s2.domainkey.u624781.wl.sendgrid.net"
},
"spf": {
"valid": false,
"type": "txt",
"host": "staples.com",
"data": "v=spf1 include:u624781.wl.sendgrid.net -all"
}
}
}

*** You will want to look for the domain whitelabel ID here if using API to do this as this will be used in the next calls to append this whitelabel to sub users. Also the records needed to validate this domain whitelabel will be passed back in the response

2. Create an IP Whitelabel
   curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: application/json” -d '{"ip": "167.89.66.50",
   "subdomain": "email",
   "domain": "staples.com"}' 'https://api.sendgrid.com/v3/whitelabel/ips'
   Successful Response => 2xx
   {
   "id": 11887,
   "ip": "167.89.66.50",
   "rdns": "o4.email.staples.com",
   "users": [],
   "subdomain": "email",
   "domain": "staples.com",
   "a_record": {
   "valid": false,
   "type": "a",
   "host": "o4.email.staples.com",
   "data": "167.89.66.50"
   },
   "valid": false,
   "legacy": false
   }

3. Create Link Whitelabel
   curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
   "domain": "staples.com",
   "subdomain": "links",
   "default": true
   }' 'https://api.sendgrid.com/v3/whitelabel/links'
   Response => 2xx
   {
   "id": 42371,
   "user_id": 624781,
   "domain": "staples.com",
   "subdomain": "links",
   "username": "ryan.burrer",
   "valid": false,
   "default": true,
   "legacy": false,
   "dns": {
   "domain_cname": {
   "valid": false,
   "type": "cname",
   "host": "links.staples.com",
   "data": "sendgrid.net"
   },
   "owner_cname": {
   "valid": false,
   "type": "cname",
   "host": "624781.staples.com",
   "data": "sendgrid.net"
   }
   }
   }

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

4. GET all domain whitelabels - grab ID to validate and associate to an acct
   curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains'
   Response = 2xx ok
   {
   "id": 50784,
   "user_id": 624781,
   "subdomain": "subdomain",
   "domain": "staples.com",
   "username": "ryan.burrer",
   "ips": [
   "167.89.38.39",
   "198.37.152.144"
   ],
   "custom_spf": false,
   "default": true,
   "legacy": false,
   "automatic_security": true,
   "valid": false,
   "dns": {
   "mail_cname": {
   "valid": false,
   "type": "cname",
   "host": "subdomain.staples.com",
   "data": "u624781.wl.sendgrid.net"
   },
   "dkim1": {
   "valid": false,
   "type": "cname",
   "host": "s1._domainkey.staples.com",
   "data": "s1.domainkey.u624781.wl.sendgrid.net"
   },
   "dkim2": {
   "valid": false,
   "type": "cname",
   "host": "s2._domainkey.staples.com",
   "data": "s2.domainkey.u624781.wl.sendgrid.net"
   },
   "spf": {
   "valid": false,
   "type": "txt",
   "host": "staples.com",
   "data": "v=spf1 include:u624781.wl.sendgrid.net -all"
   }
   }
   },

5. Once you have the ID of the domain whitelabel you can validate
   curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains/50784/validate'
   Response => 2xx
   { "id”: 50784, "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 } } }

6. Once validated you can associate to any subuser accounts

curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
"username": "ryancurltesting"
}' 'https://api.sendgrid.com/v3/whitelabel/domains/50784/subuser'
7) Follow the same process with Link branding:
-> GET link ID (ex. 42371)
curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -'https://api.sendgrid.com/v3/whitelabel/links'

Response => 200 ok
[
{
"id": 203,
"user_id": 624781,
"domain": "burnsey.me",
"subdomain": "links",
"username": "ryan.burrer",
"valid": true,
"default": false,
"legacy": false,
"dns": {
"domain_cname": {
"valid": true,
"type": "cname",
"host": "links.burnsey.me",
"data": "sendgrid.net"
},
"owner_cname": {
"valid": true,
"type": "cname",
"host": "624781.burnsey.me",
"data": "sendgrid.net"
}
}
},
{
"id": 202,
"user_id": 624781,
"domain": "burnsey.org",
"subdomain": "links",
"username": "ryan.burrer",
"valid": true,
"default": false,
"legacy": false,
"dns": {
"domain_cname": {
"valid": true,
"type": "cname",
"host": "links.burnsey.org",
"data": "sendgrid.net"
},
"owner_cname": {
"valid": true,
"type": "cname",
"host": "624781.burnsey.org",
"data": "sendgrid.net"
}
}
},
{
"id": 42371,
"user_id": 624781,
"domain": "staples.com",
"subdomain": "links",
"username": "ryan.burrer",
"valid": false,
"default": true,
"legacy": false,
"dns": {
"domain_cname": {
"valid": false,
"type": "cname",
"host": "links.staples.com",
"data": "sendgrid.net"
},
"owner_cname": {
"valid": false,
"type": "cname",
"host": "624781.staples.com",
"data": "sendgrid.net"
}
}
}
]

-> 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 => 200 ok
{
"id": 203,
"valid": true,
"validation_results": {
"domain_cname": {
"valid": true,
"reason": null
},
"owner_cname": {
"valid": true,
"reason": null
}
}
}

-> 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 => 201 created
{
"id": 200,
"user_id": 623032,
"domain": "burnsey.me",
"subdomain": "links",
"username": "ryan.burrer@sendgrid.com",
"valid": false,
"default": false,
"legacy": false,
"dns": {
"domain_cname": {
"valid": false,
"type": "cname",
"host": "links.burnsey.me",
"data": "sendgrid.net"
},
"owner_cname": {
"valid": true,
"type": "cname",
"host": "623032.burnsey.me",
"data": "sendgrid.net"}}}

[crweiner]

I am working on this now. 👍

[crweiner]

@ksigler7 Please see #4182 for my attempt at making the Automating Subusers page. I have currently titled my PR as [Do Not Merge] because I wanted to have your input for any and all edits before my PR is considered for the Docs.