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 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
JSON
XML
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
{
"credit": "200",
"credit_remain": "200",
"last_reset": "2014-11-21"
}
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
<credits>
<credit>200</credit>
<credit_remain>200</credit_remain>
<last_reset>2014-11-21</last_reset>
</credits>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<result>
<message>success</message>
</result>
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
JSON
XML
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
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
<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.