Subuser Management

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

In both creating and searching for a subuser, use the username parameter. In other API calls, 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 Knowledge Center article.

Create a Subuser

URI Parameter	Required	Requirements	Description
username	Yes	No more than 64 characters	New subuser username
password	Yes	See SendGrid password requirements	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 domain authentication record on the parent user	New subuser authenticated domain. Be mindful of IP assignment in relation to authenticated domain record

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 Sesame Street"&city="New York"&state=NY&zip=10128&email=subuser@domain.com&country=US&phone="(999) 555-5555"`

Response

{
  "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 Sesame Street"&city="New York"&state=NY&zip=10128&email=subuser@domain.com&country=US&phone="(999) 555-5555"`

Response

<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.

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

Call

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

Response

{
  "message": "success"
}

Call

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

Response

<result>
   <message>success</message>
</result>

Retrieve Subusers

Obtain a list of subusers under your account.

URI 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

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

[
  {
    "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

<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.

URI 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

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

{
  "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

<result>
   <message>success</message>
</result>

Update Subuser Password

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

URI Parameter	Required	Requirements	Description
user	Yes	Subuser must be under your account	Subuser to update password of
password	Yes	See SendGrid password requirements	New password for subuser
confirm_password	Yes	Match `password` argument	Confirm new password

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

{
  "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

<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.

URI 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

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

{
  "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

<result>
   <message>success</message>
</result>

Update Subuser Profile

Update Subuser profile information.

URI 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

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

{
  "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

<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.

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

Call

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

Response

{
  "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

<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.

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

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

{
  "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

<result>
   <message>success</message>
</result>

Disable Website Access To A Subuser

When you disable website access for a Subuser, website access will also be disabled for all of that Subuser's Teammates.

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

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

Call

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

Response

{
  "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

<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.

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

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

{
  "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

<result>
   <message>success</message>
</result>

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

This documentation is for the SendGrid Web API v2

Need some help?

Thank you for your feedback!

Thanks for your feedback!