Account Limits

When you need your subuser to send only a specific amount of emails at a specified interval, you can set account limits, or throttle their sending capabilities.

Retrieve

Retrieve account limits for a specific subuser. If the API call response is empty that means the subuser has the limits removed.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `retrieve`	Task to retrieve account limits
user	Yes	Subuser must be under your account	The subuser who will have their account limits retrieved

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=retrieve`

Response

{
  "credit": "200",
  "credit_remain": "200",
  "last_reset": "2014-11-21"
}

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=retrieve`

Response

<credits>
   <credit>200</credit>
   <credit_remain>200</credit_remain>
   <last_reset>2014-11-21</last_reset>
</credits>

No Limit

Remove the limit for a subuser.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `none`	Task to remove account limits
user	Yes	Subuser must be under your account	The subuser who will have their credit limits removed

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=none`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=none`

Response

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

Recurring Reset

A recurring reset will allow you to periodically reset a subusers credits to a number you specify. This can be daily, weekly, or monthly.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `recurring`	Task to setup recurring credits
user	Yes	Subuser must be under your account	The subuser you will be applying a recurring credit limit to
credits	Yes	Unsigned integer	The number of credits the subuser will be reset to
period	Yes	Must be either daily, weekly, or monthly	How often you want SendGrid to reset the subuser credits
startdate	No	Date must be in `YYYY-mm-dd` format	The date you want to start resetting the subuser credits
enddate	No	Date must be in `YYYY-mm-dd` format	The date you want to stop resetting the subusers credits. After this date, credits will not be added to the account, but can still be consumed
initial_credits	No	Unsigned integer	The number of credits you initially want the account reset to. If this is not set, the credits will be reset using the credits parameter. Useful when setting up a subuser with partially-consumed credits

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=recurring&credits=200&period=daily`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=recurring&credits=200&period=daily`

Response

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

Total Credits

Set a subusers credits to a specified amount.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `total`	Task to set the credits to the specified amount
user	Yes	Subuser must be under your account	The subuser who will have their credits updated
credits	Yes	Unsigned integer	The total number of credits the subuser will be set to

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=total&credits=200`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=total&credits=200`

Response

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

Increment Credits

Set the number of credits that a subuser can use.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `increment`	Task to increment the credits by the specified amount
user	Yes	Subuser must be under your account	The subuser who will have their credits incremented
credits	Yes	Unsigned integer	The total number of credits the subuser will be incremented by

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=increment&credits=20`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=increment&credits=20`

Response

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

Decrement Credits

Remove credits from a subuser.

URI Parameter	Required	Requirements	Description
task	Yes	Must be set to `decrement`	Task to decrement the credits by the specified amount
user	Yes	Subuser must be under your account	The subuser who will have their credits decremented
credits	Yes	Unsigned integer	The total number of credits the subuser will be decremented by

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.json`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=decrement&credits=200`

Response

{
  "message": "success"
}

Call

POST	`https://api.sendgrid.com/apiv2/customer.limit.xml`
POST Data	`api_user=your_sendgrid_username&api_key=your_sendgrid_password&user=subuser_username&task=decrement&credits=200`

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!