From 0f2d34e717b268a1098f75f95f994d3730f9a3f9 Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Thu, 11 Oct 2018 12:28:33 -0400 Subject: [PATCH 01/10] Create automating-subusers.md --- .../sending-email/automating-subusers.md | 513 ++++++++++++++++++ 1 file changed, 513 insertions(+) create mode 100644 content/docs/for-developers/sending-email/automating-subusers.md diff --git a/content/docs/for-developers/sending-email/automating-subusers.md b/content/docs/for-developers/sending-email/automating-subusers.md new file mode 100644 index 0000000000..6b67708306 --- /dev/null +++ b/content/docs/for-developers/sending-email/automating-subusers.md @@ -0,0 +1,513 @@ +--- +seo: + title: Automate Adding Subusers with the SendGrid API + description: Use the SendGrid API to add Subusers to your account. + keywords: Getting Started, API, v3, REST, SendGrid REST API, Subuser +title: Automate Adding Subusers with the SendGrid API +group: api-v3 +weight: 100 +layout: page +navigation: + show: true +--- + +You can utalize 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 + +Before you can start using the API, you need to do the following: + +1. Create a SendGrid [account](https://sendgrid.com/pricing/). +2. Create an [API Key](https://app.sendgrid.com/settings/api_keys). +3. Make sure you have [curl](https://curl.haxx.se/) installed on your machine. + + + +curl comes standard on Mac operating systems. + + + +## How to add a Subuser via the SendGrid API and curl + +### Creating the Subuser + +1. **Create Subuser** - Creating the actual account, the profile, username, password, and the keys you want on the account. + +```bash +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: + +```bash +=> 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): + +```bash +curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/subusers' +``` +Response: +```bash +[{"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: + +```bash +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: + +```bash +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: + + ```bash + => +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 account in question + +1. **Click Tracking** + +```bash +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: + +```bash +=> 200 OK +{"enable_text":true,"enabled":true} +``` +2. **Open Tracking** + +```bash +curl -X PATCH -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"enabled": true}' 'https://api.sendgrid.com/v3/tracking_settings/open' +``` + +Response: + +```bash +=> 200 ok +{"enabled":true} +``` + +3. **Webhook** - Event Notification App + +```bash +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: + +```bash +=> 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"} +``` + + +### Whitelabel the Subuser + +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** + +```bash +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' +``` + +Response: + +```bash +=> 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, as this will be used in the next calls to append this Whitelabel to Subusers. Also, the records needed to validate this domain Whitelabel will be passed back in the response. + +2. **Create an IP Whitelabel** + +```bash +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: + ```bash + => 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** + +```bash +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: +```bash +=> 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 the ID to validate and associate to an account. + +```bash +curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains' +``` + +Response: + +```bash += 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. **Validate ID of domain Whitelabel** +Once you have the ID of the domain whitelabel you can validate it. + +```bash +curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains/50784/validate' +```` + +Response: + +```bash +=> 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. **Associate with a Subuser** +Once Validated, you can associate to any Subuser accounts. + +```bash +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. **Link Branding** +Follow the same process with Link branding: + +```bash +-> 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: + +```bash + => 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: + +```bash +curl -X POST -H "Authorization: Basic XXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/links/203/validate' +``` + +Response: + +```bash +=> 200 ok +{ +"id": 203, +"valid": true, +"validation_results": { +"domain_cname": { +"valid": true, +"reason": null +}, +"owner_cname": { +"valid": true, +"reason": null +} +} +} +``` + +Associate Link Branding: + +```bash +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: + +```bash +=> 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"}}} +``` + +## Next Steps + +For more information on SendGrid and where you can go from here, check out these pages: + +- [API Reference]({{root_url}}/api-reference/) +- [Sender Authentication]({{root_url}}/ui/account-and-settings/how-to-set-up-domain-authentication/) +- [How to Send Email]({{root_url}}/ui/sending-email/how-to-send-email-with-marketing-campaigns/) From d063e0c34cc5cf55b353949978e7492f92402e12 Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Thu, 11 Oct 2018 12:34:59 -0400 Subject: [PATCH 02/10] Add link to Automating Subusers --- content/docs/for-developers/sending-email/api-getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/for-developers/sending-email/api-getting-started.md b/content/docs/for-developers/sending-email/api-getting-started.md index 64e0efaf67..69bc434dd7 100644 --- a/content/docs/for-developers/sending-email/api-getting-started.md +++ b/content/docs/for-developers/sending-email/api-getting-started.md @@ -82,4 +82,5 @@ For more information on SendGrid and where you can go from here, check out these - [API Reference]({{root_url}}/api-reference/) - [Sender Authentication]({{root_url}}/ui/account-and-settings/how-to-set-up-domain-authentication/) +- [Automating Subusers]({{root_url}}/for-developers/sending-email/automating-subusers.md) - [How to Send Email]({{root_url}}/ui/sending-email/how-to-send-email-with-marketing-campaigns/) From c4daae2b7554f0ca03928df1a8a4eb40308c9186 Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Thu, 11 Oct 2018 12:37:12 -0400 Subject: [PATCH 03/10] Fix spelling errors and typos --- .../sending-email/automating-subusers.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/content/docs/for-developers/sending-email/automating-subusers.md b/content/docs/for-developers/sending-email/automating-subusers.md index 6b67708306..cedabc235a 100644 --- a/content/docs/for-developers/sending-email/automating-subusers.md +++ b/content/docs/for-developers/sending-email/automating-subusers.md @@ -11,7 +11,7 @@ navigation: show: true --- -You can utalize 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. +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 @@ -61,7 +61,7 @@ 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: +3. **Create API Keys** (optional, depends on integration style): If the application would rather run on API keys than a password, then follow this step: ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"name": “API KEY NAME"}' 'https://api.sendgrid.com/v3/api_keys' @@ -75,18 +75,17 @@ curl -X POST -H "Authorization: Bearer PARENT_APIKEY_HERE" 'https://api.sendgrid.com/v3/api_keys' ``` - Successful API key implementation Response: +Successful API key implementation Response: ```bash - => -201 created + => 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. +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 +As of right now this needs to be done directly through the account in question. 1. **Click Tracking** @@ -142,7 +141,7 @@ Response: ### Whitelabel the Subuser -Now we’re going to whitelabel the subusers created above. This process involves creating the parent whitelabel and then associating it with your subusers: +Now we are 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** @@ -335,7 +334,7 @@ Response: ``` 5. **Validate ID of domain Whitelabel** -Once you have the ID of the domain whitelabel you can validate it. +Once you have the ID of the domain Whitelabel you can Validate it. ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains/50784/validate' From abd279aef22ddc4f60a6c6f6c69864a79d8855d6 Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Thu, 11 Oct 2018 17:17:32 -0400 Subject: [PATCH 04/10] Add link to "How to Create a Subuser with the API" --- content/docs/for-developers/sending-email/automating-subusers.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/for-developers/sending-email/automating-subusers.md b/content/docs/for-developers/sending-email/automating-subusers.md index cedabc235a..836c68d9cc 100644 --- a/content/docs/for-developers/sending-email/automating-subusers.md +++ b/content/docs/for-developers/sending-email/automating-subusers.md @@ -508,5 +508,6 @@ Response: For more information on SendGrid and where you can go from here, check out these pages: - [API Reference]({{root_url}}/api-reference/) +- [How to Create a Subuser with the API]({{root_url}}/for-developers/sending-email/how-to-create-a-subuser-with-the-api) - [Sender Authentication]({{root_url}}/ui/account-and-settings/how-to-set-up-domain-authentication/) - [How to Send Email]({{root_url}}/ui/sending-email/how-to-send-email-with-marketing-campaigns/) From c41859681ce1e52c43689e6f27dc9f15e70d5893 Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Thu, 11 Oct 2018 17:19:14 -0400 Subject: [PATCH 05/10] Add link to "Automating Subusers" --- .../sending-email/how-to-create-a-subuser-with-the-api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md b/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md index 2fda0aa288..c735f5b21e 100644 --- a/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md +++ b/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md @@ -120,6 +120,7 @@ https://api.sendgrid.com/apiv2/customer.auth.json?api_user=ryan.burrer@sendgrid. ## Additonal Resources +* [Automating Subusers]({{root_url}}/docs/for-developers/sending-email/automating-subusers) * [Event Notification URL]({{root_url}}/API_Reference/Customer_Subuser_API/event_notification_url.html) * [Apps]({{root_url}}/API_Reference/Customer_Subuser_API/apps.html) * [Account Limits]({{root_url}}/API_Reference/Customer_Subuser_API/account_limits.html) From f799da7fa33ad8904162c65789fbbe19fb8e8bd7 Mon Sep 17 00:00:00 2001 From: Carly Vanderwert Date: Fri, 12 Oct 2018 14:03:26 -0600 Subject: [PATCH 06/10] Update api-getting-started.md --- .../docs/for-developers/sending-email/api-getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-developers/sending-email/api-getting-started.md b/content/docs/for-developers/sending-email/api-getting-started.md index 69bc434dd7..5062ec1154 100644 --- a/content/docs/for-developers/sending-email/api-getting-started.md +++ b/content/docs/for-developers/sending-email/api-getting-started.md @@ -82,5 +82,5 @@ For more information on SendGrid and where you can go from here, check out these - [API Reference]({{root_url}}/api-reference/) - [Sender Authentication]({{root_url}}/ui/account-and-settings/how-to-set-up-domain-authentication/) -- [Automating Subusers]({{root_url}}/for-developers/sending-email/automating-subusers.md) +- [Automating Subusers]({{root_url}}/for-developers/sending-email/automating-subusers/) - [How to Send Email]({{root_url}}/ui/sending-email/how-to-send-email-with-marketing-campaigns/) From 3d06bd3a21a108e3dd28bc784437052f5b18aab7 Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Wed, 17 Oct 2018 11:28:42 -0400 Subject: [PATCH 07/10] Update to fix standards and wording --- .../sending-email/automating-subusers.md | 127 ++++++++++-------- 1 file changed, 69 insertions(+), 58 deletions(-) diff --git a/content/docs/for-developers/sending-email/automating-subusers.md b/content/docs/for-developers/sending-email/automating-subusers.md index 836c68d9cc..5ad94d9029 100644 --- a/content/docs/for-developers/sending-email/automating-subusers.md +++ b/content/docs/for-developers/sending-email/automating-subusers.md @@ -35,8 +35,8 @@ curl comes standard on Mac operating systems. ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{ - "username": “YOUR NEW SUBUSER USERNAME", - "email": “CONTACT EMAIL", + "username": “examplecurltesting", + "email": "example@example.com", "password": “PASSWORD", "ips": [ "167.89.38.39", @@ -48,7 +48,7 @@ The successful Response looks like this: ```bash => 2xx -{"username”:”YOUR NEW SUBUSER NAME","user_id":1868534,"email”:”YOUR CONTACT EMAIL","signup_session_token":"","authorization_token":"","credit_allocation":{"type":"unlimited"}} +{"username”:”examplecurltesting","user_id":1868534,"email”:”example@example.com","signup_session_token":"","authorization_token":"","credit_allocation":{"type":"unlimited"}} ``` 2. **GET Subusers** (optional step to confirm POST): @@ -56,9 +56,11 @@ The successful Response looks like this: ```bash curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/subusers' ``` + Response: + ```bash -[{"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"}] +[{"disabled":false,"email":"example@example.com","id":1762958,"username":"exampletestingv3subuserapi"},{"disabled":false,"email":"example@testsite.com","id":1766771,"username":"examplesubuser-UI"},{"disabled":false,"email":"example@testsite.com","id":1803837,"username":"exampleisasubuser"},{"disabled":false,"email":"example@example.com","id":1868534,"username":"examplecurltesting"}] ``` 3. **Create API Keys** (optional, depends on integration style): If the application would rather run on API keys than a password, then follow this step: @@ -66,11 +68,12 @@ Response: ```bash 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: ```bash curl -X POST -H "Authorization: Bearer PARENT_APIKEY_HERE" - -H "On-Behalf-Of: SUBUSER_NAME" \ + -H "On-Behalf-Of: examplecurltesting" \ -H "Content-Type: application/json" -d '{"name": “API KEY NAME"}' \ 'https://api.sendgrid.com/v3/api_keys' ``` @@ -87,7 +90,7 @@ Once this has been done, the Subuser has been created. From this point on, we’ ### Enable/Edit Applications As of right now this needs to be done directly through the account in question. -1. **Click Tracking** +**Click Tracking** ```bash 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' @@ -99,7 +102,8 @@ Response: => 200 OK {"enable_text":true,"enabled":true} ``` -2. **Open Tracking** + +**Open Tracking** ```bash curl -X PATCH -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{"enabled": true}' 'https://api.sendgrid.com/v3/tracking_settings/open' @@ -112,7 +116,7 @@ Response: {"enabled":true} ``` -3. **Webhook** - Event Notification App +**Event Webhook** ```bash 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' @@ -139,15 +143,16 @@ Response: ``` -### Whitelabel the Subuser +### Domain Authentication for the Subuser + +Now we are going to setup Domain Authentication for the Subusers created above. This process involves creating the parent Whitelabel and then associating it with your Subusers: -Now we are 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** ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{ - "domain": "staples.com", + "domain": "example.com", "subdomain": "subdomain", "ips": [ "167.89.38.39", @@ -163,14 +168,14 @@ Response: ```bash => 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":"example.com","username":"examplecurltesting","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.example.com","data":"u624781.wl.sendgrid.net"},"dkim1":{"valid":false,"type":"cname","host":"s1._domainkey.example.com","data":"s1.domainkey.u624781.wl.sendgrid.net"},"dkim2":{"valid":false,"type":"cname","host":"s2._domainkey.example.com","data":"s2.domainkey.u624781.wl.sendgrid.net"},"spf":{"valid":false,"type":"txt","host":"example.com","data":"v=spf1 include:u624781.wl.sendgrid.net -all"}}} { "id": 50784, "user_id": 624781, "subdomain": "subdomain", -"domain": "staples.com", -"username": "ryan.burrer", +"domain": "example.com", +"username": "examplecurltesting", "ips": [ "167.89.38.39", "198.37.152.144" @@ -184,38 +189,39 @@ Response: "mail_cname": { "valid": false, "type": "cname", -"host": "subdomain.staples.com", +"host": "subdomain.example.com", "data": "u624781.wl.sendgrid.net" }, "dkim1": { "valid": false, "type": "cname", -"host": "s1._domainkey.staples.com", +"host": "s1._domainkey.example.com", "data": "s1.domainkey.u624781.wl.sendgrid.net" }, "dkim2": { "valid": false, "type": "cname", -"host": "s2._domainkey.staples.com", +"host": "s2._domainkey.example.com", "data": "s2.domainkey.u624781.wl.sendgrid.net" }, "spf": { "valid": false, "type": "txt", -"host": "staples.com", +"host": "example.com", "data": "v=spf1 include:u624781.wl.sendgrid.net -all" } } ``` -You will want to look for the domain Whitelabel ID here, as this will be used in the next calls to append this Whitelabel to Subusers. Also, the records needed to validate this domain Whitelabel will be passed back in the response. +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. + -2. **Create an IP Whitelabel** +2. **Create Reverse DNS** ```bash 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' + "domain": "example.com"}' 'https://api.sendgrid.com/v3/whitelabel/ips' ``` Successful Response: @@ -224,14 +230,14 @@ curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: applica { "id": 11887, "ip": "167.89.66.50", - "rdns": "o4.email.staples.com", + "rdns": "o4.email.example.com", "users": [], "subdomain": "email", - "domain": "staples.com", + "domain": "example.com", "a_record": { "valid": false, "type": "a", - "host": "o4.email.staples.com", + "host": "o4.email.example.com", "data": "167.89.66.50" }, "valid": false, @@ -239,11 +245,12 @@ curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: applica } ``` -3. **Create link Whitelabel** + +3. **Create Link Branding** ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{ - "domain": "staples.com", + "domain": "example.com", "subdomain": "links", "default": true }' 'https://api.sendgrid.com/v3/whitelabel/links' @@ -255,9 +262,9 @@ Response: { "id": 42371, "user_id": 624781, -"domain": "staples.com", +"domain": "example.com", "subdomain": "links", -"username": "ryan.burrer", +"username": "examplecurltesting", "valid": false, "default": true, "legacy": false, @@ -265,13 +272,13 @@ Response: "domain_cname": { "valid": false, "type": "cname", -"host": "links.staples.com", +"host": "links.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": false, "type": "cname", -"host": "624781.staples.com", +"host": "624781.example.com", "data": "sendgrid.net" } } @@ -279,7 +286,8 @@ Response: ``` After creating DNS records then wait for them to propagate and validate records. -4. **GET all domain Whitelabels** - grab the ID to validate and associate to an account. + +4. **GET all Domain Authentication IDs** - grab the ID to validate and associate to an account. ```bash curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains' @@ -293,8 +301,8 @@ Response: "id": 50784, "user_id": 624781, "subdomain": "subdomain", -"domain": "staples.com", -"username": "ryan.burrer", +"domain": "example.com", +"username": "examplecurltesting", "ips": [ "167.89.38.39", "198.37.152.144" @@ -308,33 +316,34 @@ Response: "mail_cname": { "valid": false, "type": "cname", -"host": "subdomain.staples.com", +"host": "subdomain.example.com", "data": "u624781.wl.sendgrid.net" }, "dkim1": { "valid": false, "type": "cname", -"host": "s1._domainkey.staples.com", +"host": "s1._domainkey.example.com", "data": "s1.domainkey.u624781.wl.sendgrid.net" }, "dkim2": { "valid": false, "type": "cname", -"host": "s2._domainkey.staples.com", +"host": "s2._domainkey.example.com", "data": "s2.domainkey.u624781.wl.sendgrid.net" }, "spf": { "valid": false, "type": "txt", -"host": "staples.com", +"host": "example.com", "data": "v=spf1 include:u624781.wl.sendgrid.net -all" } } } ``` -5. **Validate ID of domain Whitelabel** -Once you have the ID of the domain Whitelabel you can Validate it. + +5. **Validate ID of the Domain Authentication** +Once you have the ID of the Domain Authentication you can Validate it. ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXXX" -H "Content-Type: application/json" 'https://api.sendgrid.com/v3/whitelabel/domains/50784/validate' @@ -347,15 +356,17 @@ Response: { "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. **Associate with a Subuser** Once Validated, you can associate to any Subuser accounts. ```bash curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{ -"username": "ryancurltesting" +"username": "examplecurltesting" }' 'https://api.sendgrid.com/v3/whitelabel/domains/50784/subuser' ```` + 7. **Link Branding** Follow the same process with Link branding: @@ -372,9 +383,9 @@ Response: { "id": 203, "user_id": 624781, -"domain": "burnsey.me", +"domain": "example.com", "subdomain": "links", -"username": "ryan.burrer", +"username": "examplecurltesting", "valid": true, "default": false, "legacy": false, @@ -382,13 +393,13 @@ Response: "domain_cname": { "valid": true, "type": "cname", -"host": "links.burnsey.me", +"host": "links.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", -"host": "624781.burnsey.me", +"host": "624781.example.com", "data": "sendgrid.net" } } @@ -396,9 +407,9 @@ Response: { "id": 202, "user_id": 624781, -"domain": "burnsey.org", +"domain": "example.org", "subdomain": "links", -"username": "ryan.burrer", +"username": "examplecurltesting", "valid": true, "default": false, "legacy": false, @@ -406,13 +417,13 @@ Response: "domain_cname": { "valid": true, "type": "cname", -"host": "links.burnsey.org", +"host": "links.example.org", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", -"host": "624781.burnsey.org", +"host": "624781.example.org", "data": "sendgrid.net" } } @@ -420,9 +431,9 @@ Response: { "id": 42371, "user_id": 624781, -"domain": "staples.com", +"domain": "example.net", "subdomain": "links", -"username": "ryan.burrer", +"username": "examplecurltesting", "valid": false, "default": true, "legacy": false, @@ -430,13 +441,13 @@ Response: "domain_cname": { "valid": false, "type": "cname", -"host": "links.staples.com", +"host": "links.example.net", "data": "sendgrid.net" }, "owner_cname": { "valid": false, "type": "cname", -"host": "624781.staples.com", +"host": "624781.example.net", "data": "sendgrid.net" } } @@ -483,9 +494,9 @@ Response: { "id": 200, "user_id": 623032, -"domain": "burnsey.me", +"domain": "example.com", "subdomain": "links", -"username": "ryan.burrer@sendgrid.com", +"username": "examplecurltesting", "valid": false, "default": false, "legacy": false, @@ -493,13 +504,13 @@ Response: "domain_cname": { "valid": false, "type": "cname", -"host": "links.burnsey.me", +"host": "links.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", -"host": "623032.burnsey.me", +"host": "623032.example.com", "data": "sendgrid.net"}}} ``` @@ -508,6 +519,6 @@ Response: For more information on SendGrid and where you can go from here, check out these pages: - [API Reference]({{root_url}}/api-reference/) -- [How to Create a Subuser with the API]({{root_url}}/for-developers/sending-email/how-to-create-a-subuser-with-the-api) +- [How to Create a Subuser with the API]({{root_url}}/for-developers/sending-email/how-to-create-a-subuser-with-the-api/) - [Sender Authentication]({{root_url}}/ui/account-and-settings/how-to-set-up-domain-authentication/) - [How to Send Email]({{root_url}}/ui/sending-email/how-to-send-email-with-marketing-campaigns/) From fa2538c6b2c14d266e32fceeb4c4b6fd85cc93fc Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Wed, 17 Oct 2018 11:30:14 -0400 Subject: [PATCH 08/10] Fix link to Automating Subusers --- .../sending-email/how-to-create-a-subuser-with-the-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md b/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md index c735f5b21e..aaacd97f7e 100644 --- a/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md +++ b/content/docs/for-developers/sending-email/how-to-create-a-subuser-with-the-api.md @@ -120,7 +120,7 @@ https://api.sendgrid.com/apiv2/customer.auth.json?api_user=ryan.burrer@sendgrid. ## Additonal Resources -* [Automating Subusers]({{root_url}}/docs/for-developers/sending-email/automating-subusers) +* [Automating Subusers]({{root_url}}/docs/for-developers/sending-email/automating-subusers/) * [Event Notification URL]({{root_url}}/API_Reference/Customer_Subuser_API/event_notification_url.html) * [Apps]({{root_url}}/API_Reference/Customer_Subuser_API/apps.html) * [Account Limits]({{root_url}}/API_Reference/Customer_Subuser_API/account_limits.html) From 6ffb170509b7e9fc45bb52b25ce4cee3aabc42ab Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Wed, 17 Oct 2018 11:36:09 -0400 Subject: [PATCH 09/10] Remove "whitelabel" reference --- .../docs/for-developers/sending-email/automating-subusers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/for-developers/sending-email/automating-subusers.md b/content/docs/for-developers/sending-email/automating-subusers.md index 5ad94d9029..002ce99e06 100644 --- a/content/docs/for-developers/sending-email/automating-subusers.md +++ b/content/docs/for-developers/sending-email/automating-subusers.md @@ -145,7 +145,7 @@ Response: ### Domain Authentication for the Subuser -Now we are going to setup Domain Authentication for the Subusers created above. This process involves creating the parent Whitelabel and then associating it with your Subusers: +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: 1. **Create Domain Authentication** From d29c179396f74c0fc153e52cde55f947366cbcce Mon Sep 17 00:00:00 2001 From: Chandler Weiner Date: Wed, 17 Oct 2018 11:40:08 -0400 Subject: [PATCH 10/10] Fix spacing --- .../docs/for-developers/sending-email/automating-subusers.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/docs/for-developers/sending-email/automating-subusers.md b/content/docs/for-developers/sending-email/automating-subusers.md index 002ce99e06..e0100a48bc 100644 --- a/content/docs/for-developers/sending-email/automating-subusers.md +++ b/content/docs/for-developers/sending-email/automating-subusers.md @@ -357,6 +357,7 @@ Response: ``` + 6. **Associate with a Subuser** Once Validated, you can associate to any Subuser accounts. @@ -367,9 +368,11 @@ curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXXX" -H "Content-Type: applica ```` + 7. **Link Branding** Follow the same process with Link branding: + ```bash -> GET link ID (ex. 42371) curl -X GET -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -'https://api.sendgrid.com/v3/whitelabel/links'