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",
      "phone": "+15555555555",
      "timezone": "Asia/Tokyo"
  },
  "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

* 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
    }
  ]
}

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.

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.