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.
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
JSON
XML
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"
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"
<result>
<message>success</message>
</result>
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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.delete.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username
POST
https://api.sendgrid.com/apiv2/customer.delete.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username
<result>
<message>success</message>
</result>
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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.profile.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=get
[
{
"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"
}
]
POST
https://api.sendgrid.com/apiv2/customer.profile.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&task=get
<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>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.disable.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password
POST
https://api.sendgrid.com/apiv2/customer.disable.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password
<result>
<message>success</message>
</result>
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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.enable.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username
POST
https://api.sendgrid.com/apiv2/customer.enable.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username
<result>
<message>success</message>
</result>
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
JSON
XML
POST
https://api.sendgrid.com/apiv2/customer.website_disable.json
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password
POST
https://api.sendgrid.com/apiv2/customer.website_disable.xml
POST Data
api_user=your_sendgrid_username&api_key=your_sendgrid_password
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>