Menu

Account Provisioning API Overview

The Account Provisioning API is in private beta and accessible by invitation only at this time.

The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.

You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio SendGrid Subusers feature, which is available with Pro and Premier plans.

Authentication and authorization

The Account Provisioning API uses standard Twilio Sendgrid API Keys for authentication and authorization. Once onboarded as a reseller, any API keys you create will have access to the Account Provisioning API. Twilio SendGrid recommends creating an Admin API key to manage your Account Provisioning API account. An Admin key is also known as a Full Access key in the Twilio SendGrid user interface.

If you are new to Twilio SendGrid API keys, see the API key docs to create an API key. The Twilio SendGrid v3 APIs expect the key to be passed as a Bearer Token in an Authorization header. See How to Use the SendGrid v3 API for instructions.

Terminology

The following documentation refers to the owner of an Account Provisioning API account as the reseller. The accounts a reseller owns and manages through this API are referred to as customer accounts. The operations available are provided to you, the reseller, in order to manage your customer accounts.

Common operations

The Twilio SendGrid Account Provisioning API allows you to create and manage your customers' accounts. This page provides an overview of the most common operations a reseller will perform:

  • Creating a customer account.
  • Understanding account state.
  • Managing customer account offerings.
  • Deactivating and removing account resources.
  • Authenticating customers with single sign-on (SSO).

For information about the other Account Provisioning API operations available, see the API reference documentation for each operation.

Creating a new customer account

Creating a new customer account is done with a single POST operation that will return the unique Twilio SendGrid account ID for the newly created account. The Create Account operation requires a JSON request body containing a profile object and an array of offerings objects.

Profile object

The profile object contains a customer's identity information such as their first_name, last_name, and email. The fields in the profile object are optional — the customer will be prompted at their first login to enter any profile information you choose not to include when creating the account. See the API reference for all profile fields.

Offerings array

The offerings array contains offering objects that list the offering's name, type, and quantity. The offerings array is required, and it defines the Twilio SendGrid features or offerings available to the customer's account. The offerings available will depend on your agreement with Twilio SendGrid.

To retrieve a list of all the offerings that you can assign to a customer account, use the List Offerings endpoint. Because the available offerings will change infrequently, you may wish to cache the List Offerings response rather than call the endpoint before each account creation or update. A new account may start on any email offering at any price point. Upgrades and downgrades are also available immediately after account provisioning.

Account creation request payload and response

The following JSON block shows a common request body used to create a new customer account.

{
  "profile": {
      "first_name": "Jane",
      "last_name": "Doe",
      "company_name": "Cake or Pie Bakery",
      "company_website": "www.example.com",
      "email": "jdoe@example.com"
  },
  "offerings": [
      {
          "name": "milne.ei.essentials-100k.v1",
          "type": "package",
          "quantity": 1
      }
    ]
}

The response to a new account creation is the Twilio Sendgrid account ID. This account ID is used in all subsequent calls to the Account Provisioning API, so you should record it in your database for future use.

{
  "account_id": "sg2a2bcd3ef4ab5c67d8efab91c01de2fa"
}

Creating a new customer test account

To create a new customer test account with Account Provisioning API, you must pass in a custom header as follows:

T-Test-Account: true

A test account will not be allocated a dedicated IP and will be limited to sending 100 email per day irrespective of the offerings used to create the account. An account not created as a test account using this custom header cannot be updated to be a test account.

Working with account state

A customer account can be in one of five states, activated, deactivated, suspended, banned, or indeterminate*. Setting the customer account state is done with a single PUT operation using one of these states. Retrieving the customer account state is done with a single GET operation that will return the state for the account. The following table shows the actions available to an account based on its state.

Table of account states and immediately affected actions

ACCOUNT STATE LOGIN SEND MAIL SUBUSERS REMOVED DEDICATED IPS REMOVED API KEYS DEACTIVATED
Activated yes yes no no no
Suspended yes no no no no
Deactivated no no no no yes
Banned no no yes yes yes

* If you find an account in the indeterminate state, please contact Twilio SendGrid support for assistance.

Managing customer account offerings

Once a customer account is created, the most common need is to upgrade or downgrade the account to a different email package, otherwise known as an "offering." In addition to common email infrastructure offerings, your partner organization may have "add-on" offerings available including features such as Marketing Campaigns, Dedicated IP Addresses, and Expert Services.

Changing an account's offerings is done with a single PUT operation requiring a JSON request body that contains an offerings array of offering objects.

Because the update operation is a PUT request, you can remove offerings by omitting them from the update request. This means you must also pass the endpoint any offerings you want the account to retain — each operation overwrites the existing offerings for the account entirely. To retrieve a list of all the offerings you may assign to a customer account, use the List Offerings endpoint. To see a list of the offerings currently assigned to an individual customer account, use the Get Account Offerings endpoint.

Update offerings request payload examples

Add package offering
{
  "offerings": [
    {
      "name": "milne.ei.essentials-100k.v1",
      "type": "package",
      "quantity": 1
    }
  ]
}
Update an account to have two dedicated IP addresses
{
  "offerings": [
    {
      "name": "milne.ei.essentials-100k.v1",
      "type": "package",
      "quantity": 1
    },
    {
      "name": "milne.x.ip.v2",
      "type": "package",
      "quantity": 2
    }
  ]
}
Downgrade an account to one dedicated IP address
{
  "offerings": [
    {
      "name": "milne.ei.essentials-100k.v1",
      "type": "package",
      "quantity": 1
    },
    {
      "name": "milne.x.ip.v2",
      "type": "package",
      "quantity": 1
    }
  ]
}
On a subsequent call, remove all dedicated IP addresses from the account
{
  "offerings": [
    {
      "name": "milne.ei.essentials-100k.v1",
      "type": "package",
      "quantity": 1
    }
  ]
}

When removing an IP Address offering, the Account Provisioning API will remove the most recently added IP address from the account. Generally speaking, mail is evenly distributed across all IP addresses, and this is the recommended methodology by Twilio Sendgrid support. If you would like to remove a specific IP address, please contact support directly.

Change offering response

The response to a change offering request is the account's resulting offerings list, which is identical to what will be returned on subsequent calls to the Get Account Offerings endpoint.

Deactivating and removing account resources

You can deactivate a customer account using the Update Account State operation to set the account state to deactivated.

{
    "state": "deactivated"
}

You can remove features such as Subusers and Dedicated IP addresses from a customer account using the Update Account Offerings operation. Update the account with a free offerings payload.

Typical free offerings payload

{
  "offerings": [
    {
      "name": "milne.ei.free-100.v1",
      "type": "package",
      "quantity": 1
    }
  ]
}

Customer SSO

Triggering SSO

Once a customer account is created, the reseller can trigger a login to the Twilio Sendgrid UI for the customer with no password needed.

Account Provisioning API SSO authentication flow

Considerations

In addition to providing a seamless customer experience for accessing the Twilio Sendgrid UI, our Account Provisioning SSO also removes the need for a Sendgrid-based username and password. The reseller can manage their customers' authentication credentials without sharing any of that information with Twilio SendGrid.

The redirect generated as part of this flow contains a one-time authorization code used to log the user into the Twilio SendGrid UI. This one-time code is good 60 seconds and can be used for login once, ensuring that any type of man-in-the-middle or replay attack can be securely blocked.

SSO will authenticate the customer as an Admin Teammate, with all the permissions to manage any aspect of the customer's account. From there, they can take all the usual steps of setting up API keys, creating additional teammates or subusers, and configuring their sender identity.

This SSO flow is limited to authentication on the base Admin Teammate. It cannot be used for SSO on a subsequently created teammate or subuser.

The Account Provisioning API does not currently support Twilio SendGrid's SAML-based SSO offering for customer accounts. All Teammates belonging to a customer account will authenticate with a username and password managed through Twilio SendGrid.

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!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more