Customer Management

Retrieve, create, enable, and disable your customers. Change a customer's email address and username. These are actions that directly affect your customer. We provide access via XML and JSON.

Create a Customer

URI Parameter	Required	Requirements	Description
username	Yes	No more than 64 characters	The customer's new username
password	Yes	See SendGrid password requirements	The customer's new password
confirm_password	Yes	Must match password parameter	Confirm new password
email	Yes	Must be in email format and no more than 64 characters	The new customer's email address
first_name	Yes	No more than 50 characters	The new customer's first name
last_name	Yes	No more than 50 characters	The new customer's last name
address	Yes	No more than 100 characters	The new customer's address
city	Yes	No more than 100 characters	The new customer's city
state	Yes	No more than 100 characters	The new customer's state
zip	Yes	No more than 50 characters	The new customer's zipcode. This field is not validated for a correct value. It is up to the developer to check for a valid zipcode.
country	Yes	No more than 100 characters	The new customer's country
phone	Yes	No more than 50 characters	The new customer's phone number
website	Yes	No more than 255 characters	The new customer's website
company	Yes	No more than 255 characters	The new customer's company
package	Yes	No more than 255 characters	Name of the Package to assign to the customer. You can view the available package here.
whitelabel	Yes	No more than 255 characters	The domain name for domain authentication. The default domain is `sendgrid.me`
ip_group[]	No	No more than 255 characters for each ip_group name. It must belong to you.	Name of the IP Group you wish to optionally add.
ip[]	No	Valid ip address that belongs to you.	If the package allows it, you can optionally add additional IP addresses.
free_user	Maybe	If the new customer is a free customer, you need to specify this parameter. Either `true` or `false`.	Create a free customer
billing_date	No	If the new customer's billing anniversary date is on a different date from the time you create the customer, you need to specify this parameter. Must be in `YYYY-mm-dd` format. This date must be within one billing cycle from the time you create this customer. (e.g. if they sign up on 2/28/11, then the latest date you can use is 3/28/11)	If the new customer's billing anniversary date is different from today (or when you execute this API call), you can specify the first billing anniversary date

Call

POST	`https://api.sendgrid.com/apiv2/reseller.add.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&username=neweexampexample@example.com&website=example.com&password=samplepassword&confirm_password=samplepassword&first_name=fname&last_name=lname&address=555_anystreet&city=any_city&state=CA&zip=91234&email=neweexampexample@example.com&country=US&phone=555-555&free_user=true&company=company&whitelabel=sendgrid.me`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.add.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&username=neweexampexample@example.com&website=example.com&password=samplepassword&confirm_password=samplepassword&first_name=fname&last_name=lname&address=555_anystreet&city=any_city&state=CA&zip=91234&email=neweexampexample@example.com&country=US&phone=555-555&free_user=true&company=company&whitelabel=sendgrid.me`

Response

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

Delete a Customer

Remove a customer from your account. This is not the same as disabling a customer on our system. This is the same thing as closing out a customer's account at the end of their billing cycle.

URI Parameter	Required	Requirements	Description
user	Yes	Must be a customer registered under your account.	The customer's username you wish to delete.

Call

POST	`https://api.sendgrid.com/apiv2/reseller.delete.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=eexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.delete.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=eexampexample@example.com`

Response

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

Retrieve Customers

Obtain a complete list of all customers.

URI Parameter	Required	Description
task	Yes	Must be set to `get` in order to retrieve user information
id	No	Search filter, id customer that is registered under you
username	No	Search filter, customer that is registered under you
email	No	Search filter, email address customer was registered with
first_name	No	Search filter, customer's first name
last_name	No	Search filter, customer's last name
address	No	Search filter, customer's address
city	No	Search filter, customer's city
state	No	Search filter, customer's state
country	No	Search filter, customer's country
zip	No	Search filter, customer's zipcode
phone	No	Search filter, customer's phone number
website	No	Search filter, customer's website
method	Yes	Must be set to `profile`
limit	No	Optional field to limit the number of results returned.
offset	No	Optional beginning point in the list to retrieve from.

Call

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

Response

[
  {
    "id": "123",
    "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"
  },
  {
    "id": "124",
    "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/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=get`

Response

<users>
   <user>
      <id>123</id>
      <username>user1</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>
      <id>124</id>
      <username>user2</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>

Enable a Customer

Enable a customer so they may start sending emails again. This call will not enable website access.

URI Parameter	Required	Requirements	Description
user	Yes	Must be a customer registered under your account.	The customer you are planning to enable
method	Yes	Must be set to `enable`	The customer you are planning to enable

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=enable&user=eexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=enable&user=eexampexample@example.com`

Response

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

Disable a Customer

This prevents a customer from sending emails with SendGrid.

URI Parameter	Required	Requirements	Description
user	Yes	Must be a customer registered under your account.	The customer you are planning to disable
method	Yes	Must be set to `disable`	The customer you are planning to disable

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=disable&user=eexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=disable&user=eexampexample@example.com`

Response

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

Enable Website Access for a Customer

Allow a customer to login to the SendGrid.com website. This call will not enable the customer to send emails.

URI Parameter	Required	Requirements	Description
user	Yes	Must be a customer registered under your account.	The customer you are planning to grant website access to
method	Yes	Must be set to `website_enable`	The customer you are planning to grant website access to

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=website_enable&user=eexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=website_enable&user=eexampexample@example.com`

Response

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

Disable Website Access for a Customer

Disallow a customer to login to the SendGrid.com website. This call will not prevent them from sending emails.

URI Parameter	Required	Requirements	Description
user	Yes	Must be a customer registered under your account.	The customer you are planning to disallow website access for
method	Yes	Must be set to `website_disable`	The customer you are planning to disallow website access for

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=website_disable&user=eexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=website_disable&user=eexampexample@example.com`

Response

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

Update Customer Profile

Allows you to update your customer's profile information

URI Parameter	Required	Description
task	Yes	Must be set to `set` in order to update profile information
method	Yes	Must be set to `profile`
user	Yes	Customer that is registered under you
first_name	No	Customer's first name
last_name	No	Customer's last name
address	No	Customer's address
city	No	Customer's city
state	No	Customer's state
country	No	Customer's country
zip	No	Customer's zipcode
phone	No	Customer's phone number
website	No	Customer's website

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=set&user=eexampexample@example.com&first_name=newFirstName&last_name=newLastName`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=set&user=eexampexample@example.com&first_name=newFirstName&last_name=newLastName`

Response

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

Update Customer Password

Passwords are encrypted by default and therefore cannot be retrieved; however, you can reset a customers password.

URI Parameter	Required	Requirements	Description
user	Yes	Customer must be registered under you	The customer whose password you are planning to reset
password	Yes	See SendGrid password requirements	Customer's new password
confirm_password	Yes	Must match password parameter	Confirm new password
method	Yes	Must be set to `password`	Allows you to access password functionality

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=password&user=eexampexample@example.com&password=newPasword&confirm_password=newPassword`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=password&user=eexampexample@example.com&password=newPasword&confirm_password=newPassword`

Response

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

Update Customer Username

Note that your customer account username is used to login to our SMTP server and the website. Changes take effect immediately.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `setUsername`	This will let us know you want to update your customer's username. This is the new username your customer will be authenticating with our SMTP servers and website. This update takes effect immediately
user	Yes	Customer must be registered under your account	The user whose username we will be updating
username	Yes	No more than 64 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 website. This update takes effect immediately
method	Yes	Must be set to `profile`	Allows you to access profile functionality

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=setUsername&user=eexampexample@example.com&username=neweexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=setUsername&user=eexampexample@example.com&username=neweexampexample@example.com`

Response

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

Update Customer Email Address

This is the contact email we use for your customers. Changes take place immediately. It is your responsibility to validate the contact email.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `setEmail`	This will let us know you want to update your customers email address. This update takes effect immediately
user	Yes	Customer must be registered under your account	The user whose username we will be updating
email	Yes	Must be in email format, not more than 100 characters	This is the new email address we will use for contacting the customer. This update takes effect immediately
method	Yes	Must be set to `password`	Allows you to access password functionality

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=setEmail&user=eexampexample@example.com&email=neweexampexample@example.com`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/reseller.manage.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&method=profile&task=setEmail&user=eexampexample@example.com&email=neweexampexample@example.com`

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!