Account Provisioning API

The Account Provisioning API uses the standard Twilio SendGrid API Keys for authentication and authorization. Once onboarded as a reseller, any API keys you create can access the Account Provisioning API. To manage your Account Provisioning API account, create an Admin API key, or a Full Access key, in the Twilio SendGrid console.

• To learn about Twilio SendGrid API keys, see create an API key. The Twilio SendGrid v3 APIs expect your app to pass the key as a Bearer Token in an Authorization header.
• To apply your API key, see How to use the Twilio SendGrid v3 API.

• Reseller: The individual that owns an Account Provisioning API account.
• Customer account: An account that a reseller owns and manages through the API.
• Offering: An email package with a set of features.

To create and manage your customers' accounts, use the Account Provisioning API. The most common operations that a reseller performs include:

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

To learn more about the other Account Provisioning API operations, see the API reference documentation for each operation.

The Create Account operation requires a JSON request body containing a profile object and an array of offerings objects. To create a customer account, make a single POST operation. This request returns the unique Twilio SendGrid account ID for the created account.

To retrieve a list of all the offerings that you can assign to a customer account, use the List Offerings endpoint. Available offerings change infrequently. Rather than call the endpoint before each account creation or update, cache the List Offerings response. An account may start on any email offering at any price point. You can upgrade or downgrade an account immediately after account provisioning.

To create a customer account, write a JSON block that resembles the following:

1
{
2
  "profile": {
3
      "first_name": "Jane",
4
      "last_name": "Doe",
5
      "company_name": "Cake or Pie Bakery",
6
      "company_website": "www.example.com",
7
      "email": "jdoe@example.com",
8
      "phone": "+15555555555",
9
      "timezone": "Asia/Tokyo"
10
  },
11
  "offerings": [
12
      {
13
          "name": "milne.ei.pro-100k.v1",
14
          "type": "package",
15
          "quantity": 1
16
      }
17
    ]
18
}

This request responds with a Twilio SendGrid account ID. All subsequent calls to the Account Provisioning API use this account ID. Record it in your database for future use.

1
{
2
  "account_id": "sg2a2bcd3ef4ab5c67d8efab91c01de2fa"
3
}

To create a new customer test account with Account Provisioning API, pass in the following custom header:

T-Test-Account: true

You can't allocate a dedicated IP address to a test account. This limits you to sending 100 email per day irrespective of the offerings used to create the account. You can't change non-test account that uses this custom header to a test account.

A customer accounts exist in one of five states, activated, deactivated, suspended, banned, or indeterminate*.

• To set the customer account state, make one PUT request with one of these states.
• To retrieve the customer account state, make one GET request that returns the state for the account.

The following table shows the actions available to an account based on its state.

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

Once you create a customer account, you might need to upgrade or downgrade the account to a different offering. Beyond common email infrastructure offerings, your partner organization might offer "add-ons" features like Marketing Campaigns, Dedicated IP address Addresses, and Expert Services.

• To change an account's offerings, make one PUT request with a JSON request body that contains an offerings array.
• To remove offerings from an account, make one PUT request that omits the offerings you want to remove from the update request.
  • In each request, pass all offerings you want to keep. Each PUT request overwrites the existing offerings for the account.
• To get a list of all the offerings that you might assign to a customer account, use the List Offerings endpoint.
• To get a list of the offerings assigned to an individual customer account, use the Get Account Offerings endpoint.

1
{
2
  "offerings": [
3
    {
4
      "name": "milne.ei.pro-100k.v1",
5
      "type": "package",
6
      "quantity": 1
7
    }
8
  ]
9
}

1
{
2
  "offerings": [
3
    {
4
      "name": "milne.ei.pro-100k.v1",
5
      "type": "package",
6
      "quantity": 1
7
    },
8
    {
9
      "name": "milne.x.ip.v2",
10
      "type": "addon",
11
      "quantity": 2
12
    }
13
  ]
14
}

1
{
2
  "offerings": [
3
    {
4
      "name": "milne.ei.pro-100k.v1",
5
      "type": "package",
6
      "quantity": 1
7
    },
8
    {
9
      "name": "milne.x.ip.v2",
10
      "type": "addon",
11
      "quantity": 1
12
    }
13
  ]
14
}

1
{
2
  "offerings": [
3
    {
4
      "name": "milne.ei.pro-100k.v1",
5
      "type": "package",
6
      "quantity": 1
7
    }
8
  ]
9
}

The change offering request returns a list of the account's offerings. This list matches the response to subsequent Get Account Offerings requests.

To manage dedicated IP addresses for their customer accounts, resellers can use the IP address Provisioning API. To support your customer requirements, you can add, list, and remove IP addresses as needed.

The most common IP address provisioning operations that a reseller uses include:

• Add IP addresses to a customer account.
• List the IP addresses assigned to a customer account.
• Remove IP addresses from a customer account.

To add IP addresses to a customer account, make one POST request. This request provisions and assigns dedicated IP addresses to the specified customer account. This request requires a JSON payload with the quantity of IP addresses and the target region.

The request payload requires two parameters:

All IP addresses in a single request must be from the same region. If you need IP addresses in multiple regions, you must make separate API calls for each region.

To add two IP addresses in the US region, include a JSON object that resembles the following:

{ "count": 2, "region": "us" }

The response returns an HTTP 201 Created status code along with the provisioned IP addresses and their region:

1
{
2
  "ips": [
3
    "192.168.1.1",
4
    "192.168.1.2"
5
  ],
6
  "region": "us"
7
}

You can use the returned IP addresses immediately with the customer account.

To get a paginated list of all IP addresses associated with a customer account, use a GET operation. This operation returns the IP addresses as last added.

By default, the endpoint returns 10 results per request.

• To change the number of results returned, pass the limit query parameter. Each operation can include up to 5,000 results.
• To paginate through results, pass the offset parameter. This gets set to the last IP address from the previous response.

The response includes an array of IP address objects, each containing the IP address and its region:

1
{
2
  "result": [
3
    {
4
      "ip": "174.0.2.1",
5
      "region": "us"
6
    },
7
    {
8
      "ip": "192.0.0.1",
9
      "region": "eu"
10
    }
11
  ],
12
  "pages": {
13
    "last": "192.0.0.1"
14
  }
15
}

To remove IP addresses from a customer account with a single DELETE operation that includes a JSON payload.

• The payload contains an array of specific IP addresses.
• Each request can remove between one and 10 IP addresses.
• Specify each IP address in standard IPv4 notation.

To remove two specific IP addresses, include a JSON object payload that resembles the following:

{ "ips": [ "174.0.0.3", "192.0.0.1" ] }

A successful response returns a 204 No Content status code. This removes the IP addresses from the customer account. When you remove an IP address from a customer account, this stops all email traffic that uses that IP address. Before removing IP addresses to avoid service disruption, update your customer's sending configuration.

To set the account state to deactivated, use the Update Account State operation.

To remove features such as Subusers and Dedicated IP addresses from a customer account, use the Update Account Offerings operation.

This example shows how to update the account with a free offerings payload.

1
{
2
  "offerings": [
3
    {
4
      "name": "milne.ei.free-100.v1",
5
      "type": "package",
6
      "quantity": 1
7
    }
8
  ]
9
}

Once you create a customer account, the reseller can trigger a login to the Twilio SendGrid console for the customer without a password.

To remove the need for a username and password, use the Account Provisioning SSO. The reseller can manage their customers' authentication credentials without sharing any data with Twilio. The redirect generated as part of this flow contains a one-time authorization code that logs the user into the Twilio SendGrid console.

• This one-time code lasts 60 seconds.
• You can use each code for login once.
• This blocks any type of man-in-the-middle or replay attack.
• SSO authenticates the customer as an Admin Teammate with all management permissions any aspect of the customer's account.
• Only the base Admin Teammate can authenticate using SSO.
• Neither teammates nor subusers can use SSO.

From there, set up API keys, create additional teammates or subusers, and configure their sender identity.