Subusers

These are actions that directly affect your subuser. We provide access via XML and JSON.

Info In both creating and searching for a subuser account, you are using the USERNAME parameter, while in all other cases you are using the USER parameter. When you are creating a subuser, there is no existing USER parameter to reference, so you are creating one. When you are searching for a subuser, you are authenticating to our servers with a valid username.

Create a Subuser

Parameter Required Requirements Description
username Yes No more than 64 characters The subusers new username
password Yes Must be at least 6 characters New password of subuser
confirm_password Yes Must match password parameter, must be at least 6 characters Confirm new password
email Yes Must be in email format, no more than 64 characters Email address of new subuser
first_name Yes No more than 50 characters First name of new subuser
last_name Yes No more than 50 characters Last name of new subuser
address Yes No more than 100 characters Address of new subuser
city Yes No more than 100 characters City of new subuser
state Yes No more than 100 characters State of new subuser
zip Yes No more than 50 characters Zip of new subuser. This field is not validated for correct value. It’s up to developer to check for valid zip code.
country Yes No more than 100 characters Country of new subuser
phone Yes No more than 50 characters Phone number of new subuser
website Yes No more than 255 characters Website of new subuser
company Yes No more than 255 characters Company of new subuser
mail_domain No A mail domain must already be setup with SendGrid, please contact support@sendgrid.com to have one setup Mail domain of new subuser

Call

1

https://sendgrid.com/apiv2/customer.add.xml?api_user=username&api_key=secureSecret&username=example@example.com&website=example.com&password=samplepassword&confirm_password=samplepassword&first_name=fname&last_name=lname&address=555v1_(deprecated)anystreet&city=anyv1_(deprecated)city&state=CA&zip=91234&email=example@example.com&country=US&phone=555-55

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.add.json?api_user=username&api_key=secureSecret&username=example@example.com&website=example.com&password=samplepassword&confirm_password=samplepassword&first_name=fname&last_name=lname&address=555v1_(deprecated)anystreet&city=anyv1_(deprecated)city&state=CA&zip=91234&email=example@example.com&country=US&phone=555-55

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3
4
5
6

{
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

Retrieve Subusers

Obtain a complete list of all subusers.
Parameter Required Description
task Yes Must be set to get in order to retrieve user information
username No Search filter, subuser that is registered under you
email No Search filter, email address subuser was registered with
active No Search filter, whether or not the subuser is currently active
first_name No Search filter, first name of subuser
last_name No Search filter, last name of subuser
address No Search filter, address of subuser
city No Search filter, city of subuser
state No Search filter, state of subuser
country No Search filter, country of subuser
zip No Search filter, zipcode of subuser
phone No Search filter, phone number of subuser
website No Search filter, website of subuser
company No Search filter, company of subuser

Call

1

https://sendgrid.com/apiv2/customer.profile.xml?api_user=username&api_key=secureSecret&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

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Call

1

https://sendgrid.com/apiv2/customer.profile.json?api_user=username&api_key=secureSecret&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"
  }
]

Enable a Subuser

Enable a subuser so they may start sending out emails again. This call will not enable website access.
Parameter Required Requirements Description
user Yes Must be in email format The subuser you are planning to enabling

Call

1

https://sendgrid.com/apiv2/customer.enable.xml?api_user=username&api_key=secureSecret&user=example@example.com

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.enable.json?api_user=username&api_key=secureSecret&user=example@example.com

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3

{
  "message": "User not found"
}

Disable a Subuser

This prevents them from sending out emails with SendGrid.
Parameter Required Requirements Description
user Yes Must be in email format The subuser you are planning to disabling

Call

1

https://sendgrid.com/apiv2/customer.disable.xml?api_user=username&api_key=secureSecret

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.disable.json?api_user=username&api_key=secureSecret

Response: Success

1

{"message":"success"}

Response: Error

1
2
3

{
  "message": "User not found"
}

Enable Website Access To A Subuser

Allow a subuser to login to the SendGrid.com website. This call will not enable the subuser to send out emails.
Parameter Required Requirements Description
user Yes Must be in email format The subuser you are planning to grant website access

Call

1

https://sendgrid.com/apiv2/customer.website_enable.xml?api_user=username&api_key=secureSecret&user=example@example.com

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.website_enable.json?api_user=username&api_key=secureSecret&user=example@example.com

Response: Success

1

{"message":"success"}

Response: Error

1
2
3

{
  "message": "User not found"
}

Disable Website Access To A Subuser

Disallow a subuser to login to the SendGrid.com website. This call will not prevent them from sending emails.
Parameter Required Requirements Description
user Yes Must be in email format The subuser you are planning to disallow website access

Call

1

https://sendgrid.com/apiv2/customer.website_disable.xml?api_user=username&api_key=secureSecret

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.website_disable.json?api_user=username&api_key=secureSecret

Response: Success

1

{"message":"success"}

Response: Error

1
2
3

{
  "message": "User not found"
}

Update Subuser Profile

Allows you to update your subusers profile information
Parameter Required Description
task Yes Must be set to set in order to update profile information
user Yes Subuser that is registered under you
first_name No First name of subuser
last_name No Last name of subuser
address No Address of subuser
city No City of subuser
state No State of subuser
country No Country of subuser
zip No Zipcode of subuser
phone No Phone number of subuser
website No Website of subuser
company No Company of subuser

Call

1

https://sendgrid.com/apiv2/customer.profile.xml?api_user=username&api_key=secureSecret&task=set&user=example@example.com&first_name=newFirstName&last_name=&newLastNam

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.profile.json?api_user=username&api_key=secureSecret&task=set&user=example@example.com&first_name=newFirstName&last_name=&newLastNam

Response: Success

1

{"message":"success"}

Response: Error

1
2
3
4
5
6

{
    "message": "error",
    "errors": [
        "...error messages..."
    ]
}

Update Subuser Password

Passwords are encrypted by default and therefore cannot be retrieved; however, you can reset a subusers password.
Parameter Required Requirements Description
user Yes Subuser must be registered under you The subuser you are planning to reset the password
password Yes Must be at least 6 characters New password of subuser
confirm_password Yes Must match password parameter and be at least 6 characters Confirm new password

Call

1

https://sendgrid.com/apiv2/customer.password.xml?api_user=username&api_key=secureSecret&user=example@example.com&password=newPasword&confirm_password=newPasswor

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.password.json?api_user=username&api_key=secureSecret&user=example@example.com&password=newPasword&confirm_password=newPasswor

Response: Success

1

{"message":"success"}

Response: Error

1
2
3
4
5
6

{
    "message": "error",
    "errors": [
        "...error messages..."
    ]
}

Update Subuser Username

Note that your subuser account username is used to login to our SMTP server and the website and changes take effect immediately.
Parameter Required Requirements Description
task Yes Must be set tosetUsername This will let us know you want to update your subusers username. This is the new username your subuser will be authenticating with our SMTP servers and to access the website. This update takes effect immediately
user Yes Subuser must be registered under your account The user we will be updating their username for
username Yes Must be in email format, not more than 100 characters, cannot be already taken and cannot contain SendGrid.com in the domain name This is the new username we will be authenticating with our SMTP servers and to access our site. This update takes effect immediately

Call

1

https://sendgrid.com/apiv2/customer.profile.xml?api_user=username&api_key=secureSecret&task=setUsername&user=example@example.com&username=newexample@example.com

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.profile.json?api_user=username&api_key=secureSecret&task=setUsername&user=example@example.com&username=newexample@example.com

Response: Success

1

{"message":"success"}

Response: Error

1
2
3
4
5
6

{
    "message": "error",
    "errors": [
        "...error messages..."
    ]
}

Update Subuser Email Address

This is the contact email we use for your subusers. Changes take place immediately. It is your responsibility to validate the contact email.
Parameter Required Requirements Description
task Yes Must be set to setEmail This will let us know you want to update your subusers email address. This update takes effect immediately
user Yes Subuser must be registered under your account The user we will be updating their username for
email Yes Must be in email format, not more than 100 characters This is the new email address we will use for contacting subuser. This update takes effect immediately

Call

1

https://sendgrid.com/apiv2/customer.profile.xml?api_user=username&api_key=secureSecret&task=setEmail&user=example@example.com&email=newexample@example.com

Response: Success

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

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

Response: Error

1
2
3
4
5

<?xml version="1.0" encoding="ISO-8859-1"?>

<result>
   <message>error: reason</message>
</result>

Call

1

https://sendgrid.com/apiv2/customer.profile.xml?api_user=username&api_key=secureSecret&task=setEmail&user=example@example.com&email=newexample@example.com

Response: Success

1

{"message":"success"}

Response: Error

1
2
3
4
5
6

{
    "message": "error",
    "errors": [
        "...error messages..."
    ]
}