Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

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 Requirements 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 Requirements 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; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.