On this page

Subuser Management

(warning)

This documentation is for the SendGrid Web API v2

We will deprecate this version on February 10, 2025. To access all the latest features and upcoming developments, please see our v3 API. For assistance with transitioning, refer to our migration guide.

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

(warning)

Warning

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.

(information)

Info

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

JSONXML

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

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

Delete a Subuser

(warning)

Warning

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

JSONXML

Call

Method	URL part
`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

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

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

JSONXML

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    "username": "username",
4    "email": "example1@example.com",
5    "active": "true",
6    "first_name": "john",
7    "last_name": "doe",
8    "address": "555 any street",
9    "city": "any city",
10    "state": "CA",
11    "zip": "91234",
12    "country": "US",
13    "phone": "555-555-5555",
14    "website": "example.com"
15  },
16  {
17    "username": "username",
18    "email": "example2@example.com",
19    "active": "false",
20    "first_name": "jane",
21    "last_name": "doe",
22    "address": "555 any street",
23    "city": "any city",
24    "state": "CA",
25    "zip": "91234",
26    "country": "US",
27    "phone": "555-555-5555",
28    "website": "example.com"
29  }
30]

Update Subuser Username

(warning)

Warning

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

JSONXML

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  "message": "success"
3}

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

JSONXML

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  "message": "success"
3}

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

JSONXML

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  "message": "success"
3}

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

JSONXML

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  "message": "success"
3}

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

JSONXML

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  "message": "success"
3}

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

JSONXML

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  "message": "success"
3}

Disable Website Access To A Subuser

(warning)

Warning

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

JSONXML

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  "message": "success"
3}

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

JSONXML

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  "message": "success"
3}