These commands allow the creation, management, and deletion of subusers.

In both creating and searching for a subuser, use the username parameter. In other commands, use the user parameter. When creating a subuser, there is no existing user parameter to reference, and one is being created.

For recommended steps when creating Subusers using the API, check out this SendGrid Knowledgebase article.

Create a Subuser

Parameter Required Requirements Description
username Yes No more than 64 characters New subuser username
password Yes At least 6 characters New subuser password
confirm_password Yes Match password argument Confirm new password
email Yes Valid email address, no more than 64 characters New subuser email. This is an administrative contact address for SendGrid
first_name Yes No more than 50 characters New subuser profile first name
last_name Yes No more than 50 characters New subuser profile last name
address Yes No more than 100 characters New subuser profile street address
city Yes No more than 100 characters New subuser profile city
state Yes No more than 100 characters New subuser profile state
zip Yes No more than 50 characters New subuser profile postal code
country Yes Valid ISO 3166-1 alpha-2 country code New subuser profile country code
phone Yes No more than 50 characters New subuser profile phone number
website Yes No more than 255 characters New subuser profile website
company Yes No more than 255 characters New subuser profile company name
mail_domain No Existing whitelabel record on the parent user New subuser whitelabel. Be mindful of IP assignment in relation to whitelabel record
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.add.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&username=subuser_username&website=domain.com&password=subuser_password&confirm_password=subuser_password&first_name=subuser_first_name&last_name=subuser_last_name&address="123

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.add.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&username=subuser_username&website=domain.com&password=subuser_password&confirm_password=subuser_password&first_name=subuser_first_name&last_name=subuser_last_name&address="123

Response

1
2
3
<result>
   <message>success</message>
</result>

Delete a Subuser

This call will delete a subuser and will disable all tracked links on sent messages. Recipients will no longer be able to click existing tracked links and make it to the intended destination. This is irreversible, and should be used with extreme caution.

Parameter Required Requirements Description
user Yes Must be existing subuser name Subuser to delete
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.delete.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&username=subuser_username

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.delete.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&username=subuser_username

Response

1
2
3
<result>
   <message>success</message>
</result>

Retrieve Subusers

Obtain a list of subusers under your account.

Parameter Required Requirements Description
task Yes Must be set to get Task to get list of subusers
username No Valid username format Optional string to filter results
email No Valid email format Optional string to filter results
active No 0 or 1 Optional flag to filter results
first_name No Valid first_name format Optional string to filter results
last_name No Valid last_name format Optional string to filter results
address No Valid street address format Optional string to filter results
city No Valid city format Optional string to filter results
state No Valid state format Optional string to filter results
country No Valid country format Optional string to filter results
zip No Valid zip format Optional string to filter results
phone No Valid phone format Optional string to filter results
website No Valid website format Optional string to filter results
company No Valid company format Optional string to filter results
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.profile.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=get

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
[
  {
    "username": "username",
    "email": "example1@example.com",
    "active": "true",
    "first_name": "john",
    "last_name": "doe",
    "address": "555 any street",
    "city": "any city",
    "state": "CA",
    "zip": "91234",
    "country": "US",
    "phone": "555-555-5555",
    "website": "example.com"
  },
  {
    "username": "username",
    "email": "example2@example.com",
    "active": "false",
    "first_name": "jane",
    "last_name": "doe",
    "address": "555 any street",
    "city": "any city",
    "state": "CA",
    "zip": "91234",
    "country": "US",
    "phone": "555-555-5555",
    "website": "example.com"
  }
]

Call

POST https://api.sendgrid.com/apiv2/customer.profile.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=get

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
<users>
   <user>
      <username>username</username>
      <email>example1@example.com</email>
      <active>true</active>
      <first_name>john</first_name>
      <last_name>doe</last_name>
      <address>
555 any street

</address>
      <city>any city</city>
      <state>CA</state>
      <zip>91234</zip>
      <country>US</country>
      <phone>555-555-5555</phone>
      <website>example.com</website>
   </user>
   <user>
      <username>username</username>
      <email>example2@example.com</email>
      <active>false</active>
      <first_name>jane</first_name>
      <last_name>doe</last_name>
      <address>
555 any street

</address>
      <city>any city</city>
      <state>CA</state>
      <zip>91234</zip>
      <country>US</country>
      <phone>555-555-5555</phone>
      <website>example.com</website>
   </user>
</users>

Update Subuser Username

Subuser username is used to access website and API. Changes occur immediately. To safely alter login credentials without access downtime, use Multiple Credentials.

Parameter Required Requirements Description
task Yes Must be set to setUsername Task to update subuser username
user Yes Subuser must be under your account Subuser to update username of
username Yes Valid username format New username for subuser
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.profile.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=setUsername&user=subuser_username&username=newsubuser_username

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.profile.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=setUsername&user=subuser_username&username=newsubuser_username

Response

1
2
3
<result>
   <message>success</message>
</result>

Update Subuser Password

Passwords are stored encrypted, and cannot be retrieved. Forgotten passwords must be updated.

Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to update password of
password Yes At least 6 characters New password for subuser
confirm_password Yes Match password argument Confirm new password
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.password.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&password=newPassword&confirm_password=newPassword

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.password.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&password=newPassword&confirm_password=newPassword

Response

1
2
3
<result>
   <message>success</message>
</result>

Update Subuser Email Address

This is the administrative contact address, used by SendGrid to contact the user. Unrelated to sending address information.

Parameter Required Requirements Description
task Yes Must be set to setEmail Task to update subuser email address
user Yes Subuser must be under your account Subuser to update email address of
email Yes Valid email format New administrative contact address
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.profile.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=setEmail&user=subuser_username&email=newsubuser_username

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.profile.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=setEmail&user=subuser_username&email=newsubuser_username

Response

1
2
3
<result>
   <message>success</message>
</result>

Update Subuser Profile

Update Subuser profile information.

Parameter Required Requirements Description
task Yes Must be set to set Task to update subuser profile
user Yes Subuser must be under your account Subuser to update profile
first_name No Valid first_name format Optional string to filter results
last_name No Valid last_name format Optional string to filter results
address No Valid street address format Optional string to filter results
city No Valid city format Optional string to filter results
state No Valid state format Optional string to filter results
country No Valid country format Optional string to filter results
zip No Valid zip format Optional string to filter results
phone No Valid phone format Optional string to filter results
website No Valid website format Optional string to filter results
company No Valid company format Optional string to filter results
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.profile.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=set&user=subuser_username&first_name=newFirstName&last_name=&newLastName

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.profile.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=set&user=subuser_username&first_name=newFirstName&last_name=&newLastName

Response

1
2
3
<result>
   <message>success</message>
</result>

Disable a Subuser

Sets subuser’s active flag to 0. Prevents subuser from sending email. Does not affect website login permissions.

Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to disable email permissions
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.disable.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.disable.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <message>success</message>
</result>

Enable a Subuser

Sets subuser’s active flag to 1. Allows subuser to send email. Does not affect website login permissions. New subusers are set to active by default.

Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to enable email permissions
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.enable.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.enable.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

1
2
3
<result>
   <message>success</message>
</result>

Disable Website Access To A Subuser

Disallow a subuser to login to the SendGrid website. Does not affect email sending permissions.

Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to disable website access
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.website_disable.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.website_disable.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
<result>
   <message>success</message>
</result>

Enable Website Access To A Subuser

Allow a subuser to login to the SendGrid website. Does not affect email sending permissions. New subusers are enabled by default.

Parameter Required Requirements Description
user Yes Subuser must be under your account Subuser to enable website access
Parameter Value Requirements Description

Call

POST https://api.sendgrid.com/apiv2/customer.website_enable.json
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/apiv2/customer.website_enable.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username

Response

1
2
3
<result>
   <message>success</message>
</result>