How to use the SendGrid V3 API

Welcome to SendGrid’s Web API v3! This API is RESTful, fully featured, easy to integrate with, and offers support in 7 different languages.


On Behalf Of

The On Behalf Of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. Use this header to automate bulk updates or to administer a Subuser or account without changing the authentication in your code.

The on-behalf-of header does not work with the Mail Send API.

How to use on-behalf-of

On Behalf Of generates the API call as if the Subuser or customer account is making the call. When authenticating and using the on-behalf-of header, you must use the parent account's API key credentials.

On Behalf Of accepts either a Subuser username or customer account ID, depending on which type of sub-account structure you are administering. Subusers function like separate SendGrid sub-accounts, and they're available to all customers on Pro and Premier plans. Customer accounts also act as separate sub-accounts that are managed by a parent account; however, customer accounts are available only to companies that have a formal reseller partnership with Twilio SendGrid.

See Subusers for more information about working with Subusers. See the Account Provisioning API for more information about managing customer accounts.

When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID.

on-behalf-of: account-id <account-id>

When making a call on behalf of a Subuser, the property value should be the Subuser's username.

on-behalf-of: <subuser-username>

curl --request GET \
  --url '' \
  --header 'authorization: Bearer <SENDGRID_API_KEY>' \
  --header 'on-behalf-of: <subuser-username>'
curl --request GET \
  --url '' \
  --header 'authorization: Bearer <SENDGRID_API_KEY>' \
  --header 'on-behalf-of: account-id <account-id>'
Rate this page:

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.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!