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.


_10curl -X POST -H "Authorization: Basic XXXXXXXXXXXXXX" -H "Content-Type: application/json" -d '{
_10  "username": “examplecurltesting",
_10  "email": "example@example.com",
_10  "password": “PASSWORD",
_10  "ips": [
_10  "167.89.38.39",
_10  "198.37.152.144"
_10  ]
_10}' 'https://api.sendgrid.com/v3/subusers'

The successful Response looks like this:


_10=> 2xx
_10{
_10  "username": "examplecurltesting",
_10  "user_id": 1868534,
_10  "email": "example@example.com",
_10  "signup_session_token": "",
_10  "authorization_token": "",
_10  "credit_allocation": { "type": "unlimited" }
_10}

GET Subusers (optional step to confirm POST ):


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

Response:


_10[
_10  { "disabled": false, "email": "example@example.com", "id": 1762958, "username": "exampletestingv3subuserapi" },
_10  { "disabled": false, "email": "example@testsite.com", "id": 1766771, "username": "examplesubuser-UI" },
_10  { "disabled": false, "email": "example@testsite.com", "id": 1803837, "username": "exampleisasubuser" },
_10  { "disabled": false, "email": "example@example.com", "id": 1868534, "username": "examplecurltesting" }
_10]

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


_10curl -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:


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

Successful API key implementation Response:


_10=> 201 created
_10{
_10  "api_key": "SG.XXXXXXXXXXXXXXXXXXXXXXXXX",
_10  "api_key_id": "sample_id",
_10  "name": "new api key",
_10  "scope_set_id": "00766089-9730-4f16-8191-b8bedc5f57f5"
_10}

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


_10curl -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:


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

Open Tracking


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

Response:


_10=> 200 ok
_10{ "enabled": true }

Event Webhook


_10curl -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:


_16=> 200 ok
_16{
_16    "bounce": true,
_16    "click": true,
_16    "deferred": true,
_16    "delivered": true,
_16    "dropped": true,
_16    "enabled": true,
_16    "group_resubscribe": true,
_16    "group_unsubscribe": true,
_16    "open": true,
_16    "processed": true,
_16    "spam_report": false,
_16    "unsubscribe": true,
_16    "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


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

Response:


_40=> 2xx
_40{
_40  "id": 50784,
_40  "user_id": 624781,
_40  "subdomain": "subdomain",
_40  "domain": "example.com",
_40  "username": "examplecurltesting",
_40  "ips": ["167.89.38.39", "198.37.152.144"],
_40  "custom_spf": false,
_40  "default": true,
_40  "legacy": false,
_40  "automatic_security": true,
_40  "valid": false,
_40  "dns": {
_40    "mail_cname": {
_40      "valid": false,
_40      "type": "cname",
_40      "host": "subdomain.example.com",
_40      "data": "u624781.wl.sendgrid.net"
_40    },
_40    "dkim1": {
_40      "valid": false,
_40      "type": "cname",
_40      "host": "s1._domainkey.example.com",
_40      "data": "s1.domainkey.u624781.wl.sendgrid.net"
_40    },
_40    "dkim2": {
_40      "valid": false,
_40      "type": "cname",
_40      "host": "s2._domainkey.example.com",
_40      "data": "s2.domainkey.u624781.wl.sendgrid.net"
_40    },
_40    "spf": {
_40      "valid": false,
_40      "type": "txt",
_40      "host": "example.com",
_40      "data": "v=spf1 include:u624781.wl.sendgrid.net -all"
_40    }
_40  }
_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


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

Successful Response:


_17 => 2xx
_17{
_17  "id": 11887,
_17  "ip": "167.89.66.50",
_17  "rdns": "o4.email.example.com",
_17  "users": [],
_17  "subdomain": "email",
_17  "domain": "example.com",
_17  "a_record": {
_17    "valid": false,
_17    "type": "a",
_17    "host": "o4.email.example.com",
_17    "data": "167.89.66.50"
_17  },
_17  "valid": false,
_17  "legacy": false
_17}

Create Link Branding


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

Response:


_25=> 2xx
_25{
_25  "id": 42371,
_25  "user_id": 624781,
_25  "domain": "example.com",
_25  "subdomain": "links",
_25  "username": "examplecurltesting",
_25  "valid": false,
_25  "default": true,
_25  "legacy": false,
_25  "dns": {
_25    "domain_cname": {
_25      "valid": false,
_25      "type": "cname",
_25      "host": "links.example.com",
_25      "data": "sendgrid.net"
_25    },
_25    "owner_cname": {
_25      "valid": false,
_25      "type": "cname",
_25      "host": "624781.example.com",
_25      "data": "sendgrid.net"
_25    }
_25  }
_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.


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

Response:


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

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


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

Response:


_14=> 2xx
_14{
_14  "id": 50784,
_14  "valid": true,
_14  "validation_results": {
_14    "mail_cname": {
_14      "valid": false,
_14      "reason": "Expected your MX record to be 'mx.sendgrid.net' but found 'example.com'."
_14    },
_14    "dkim1": { "valid": true, "reason": null },
_14    "dkim2": { "valid": true, "reason": null },
_14    "spf": { "valid": true, "reason": null }
_14  }
_14}

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


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

Link Branding Follow the same process with Link branding:


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

Response:


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

Validate Link Branding:


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

Response:


_15=> 200 ok
_15{
_15  "id": 203,
_15  "valid": true,
_15  "validation_results": {
_15    "domain_cname": {
_15      "valid": true,
_15      "reason": null
_15    },
_15    "owner_cname": {
_15      "valid": true,
_15      "reason": null
_15    }
_15  }
_15}

Associate Link Branding:


_10curl -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:


_25=> 201 created
_25{
_25  "id": 200,
_25  "user_id": 623032,
_25  "domain": "example.com",
_25  "subdomain": "links",
_25  "username": "examplecurltesting",
_25  "valid": false,
_25  "default": false,
_25  "legacy": false,
_25  "dns": {
_25    "domain_cname": {
_25      "valid": false,
_25      "type": "cname",
_25      "host": "links.example.com",
_25      "data": "sendgrid.net"
_25    },
_25    "owner_cname": {
_25      "valid": true,
_25      "type": "cname",
_25      "host": "623032.example.com",
_25      "data": "sendgrid.net"
_25    }
_25  }
_25}

Next Steps

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