The Twilio SendGrid Subusers API allows you to create and manage your Subuser accounts. Subusers are available on [Pro and Premier plans](https://sendgrid.com/pricing), and you can think of them as sub-accounts. Each Subuser can have its own sending domains, IP addresses, and reporting. SendGrid recommends creating Subusers for each of the different types of emails you sendone Subuser for transactional emails and another for marketing emails.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Subusers
summary: The Twilio SendGrid Subusers API allows you to create and manage your Subuser
accounts.
description: "The Twilio SendGrid Subusers API allows you to create and manage your\
\ Subuser accounts. Subusers are available on [Pro and Premier plans](https://sendgrid.com/pricing),\
\ and you can think of them as sub-accounts. Each Subuser can have its own sending\
\ domains, IP addresses, and reporting. SendGrid recommends creating Subusers\
\ for each of the different types of emails you send\u2014one Subuser for transactional\
\ emails and another for marketing emails. Independent Software Vendor (ISV) customers\
\ may also create Subusers for each of their customers.\n\nYou can also manage\
\ Subusers in the [Twilio SendGrid application user interface](https://app.sendgrid.com/settings/subusers).\
\ See [**Subusers**](https://docs.sendgrid.com/ui/account-and-settings/subusers)\
\ for more information."
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: subusers
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
paths:
/v3/subusers:
get:
operationId: ListSubuser
summary: List all Subusers
tags:
- Subusers
description: '**This endpoint allows you to retrieve a paginated list of all
your subusers.**
You can use the `username` query parameter to filter the list for specific
subusers.
You can use the `limit` query parameter to set the page size. If your list
contains more items than the page size permits, you can make multiple requests.
Use the `offset` query parameter to control the position in the list from
which to start retrieving additional items.'
parameters:
- name: username
in: query
description: The username of this subuser.
schema:
type: string
- name: limit
in: query
description: '`limit` sets the page size, i.e. maximum number of items from
the list to be returned for a single API request. If omitted, the default
page size is used.'
schema:
type: integer
- name: region
in: query
description: Filter for Subusers in this region. If not provided, all Subusers
will be returned. All users can also be explicitly requested by using the
filter `all`. Users who are not pinned to a region will be displayed as
`global`.
schema:
type: string
default: all
$ref: '#/components/schemas/Region'
- name: include_region
in: query
description: Optional flag to include the regions of the Subusers in the response.
If not provided, the region will be omitted from the response.
schema:
type: boolean
default: false
- $ref: '#/components/parameters/PaginationCommonOffset'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Subuser'
examples:
response:
value:
- disabled: false
email: [email protected]
id: 1234
username: example_subuser
- disabled: false
email: [email protected]
id: 1234
username: example_subuser2
'401':
description: Unexpected error in API call. See HTTP response body for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
post:
operationId: CreateSubuser
summary: Create Subuser
tags:
- Subusers
description: '**This endpoint allows you to create a new subuser.**'
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: The username for this subuser.
email:
type: string
description: The email address of the subuser.
format: email
password:
type: string
description: The password this subuser will use when logging into
SendGrid.
ips:
type: array
description: The IP addresses that should be assigned to this subuser.
items:
type: string
format: ipv4
region:
type: string
description: The region this Subuser should be assigned to. Can
be `global` or `eu`. (Regional email is in Public Beta and requires
SendGrid Pro plan or above.).
default: global
$ref: '#/components/schemas/Region1'
include_region:
type: boolean
description: A flag that determines if the Subuser's region should
be returned in the response. (Regional email is in Public Beta
and requires SendGrid Pro plan or above.)
default: false
required:
- username
- email
- password
- ips
example:
username: [email protected]
email: [email protected]
password: johns_password
ips:
- 1.1.1.1
- 2.2.2.2
region: global
include_region: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubuserPost'
examples:
response:
value:
username: example_subuser
user_id: 1234
email: [email protected]
credit_allocation:
type: unlimited
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- message: username exists
- message: unable to validate IPs at this time
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- message: you dont have permission to access this resource
'500':
description: ''
content:
application/json:
schema:
type: object
examples:
response:
value:
errors:
- message: unable to validate IPs at this time
/v3/subusers/{subuser_name}:
parameters:
- $ref: '#/components/parameters/UserName'
patch:
operationId: UpdateSubuser
summary: Enable/disable a subuser
tags:
- Subusers
description: '**This endpoint allows you to enable or disable a subuser.**'
requestBody:
content:
application/json:
schema:
type: object
properties:
disabled:
type: boolean
description: Whether or not this subuser is disabled. `true` means
disabled, `false` means enabled.
example:
disabled: false
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- message: invalid username
- message: no fields provided
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- message: unable to enable user
delete:
operationId: DeleteSubuser
summary: Delete a subuser
tags:
- Subusers
description: '**This endpoint allows you to delete a subuser.**
This is a permanent action. Once deleted, a subuser cannot be retrieved.'
responses:
'204':
description: ''
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
/v3/subusers/{subuser_name}/website_access:
parameters:
- name: subuser_name
in: path
required: true
schema:
type: string
patch:
operationId: UpdateSubuserWebsiteAccess
summary: Enable/Disable website access for a Subuser
tags:
- Subuser Website Access
description: Enable/Disable website access for a Subuser, while still preserving
email send functionality.
requestBody:
content:
application/json:
schema:
type: object
properties:
disabled:
type: boolean
description: Whether or not to disable website access to the Subuser.
`true` means disabled, `false` means enabled.
example:
disabled: true
responses:
'204':
description: ''
/v3/subusers/{subuser_name}/credits:
parameters:
- $ref: '#/components/parameters/UserName'
get:
operationId: GetSubuserCredit
summary: Get the Credits for a Subuser
tags:
- Subusers
description: '**This endpoint allows you to retrieve a Credits overview for
a Subuser.**'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubuserCredits'
examples:
response:
value:
remain: 99
total: 100
used: 1
type: recurring
reset_frequency: monthly
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: No user found
put:
operationId: UpdateSubuserCredit
summary: Update the Credits for a Subuser
tags:
- Subusers
description: '**This endpoint allows you to update the Credits for a Subuser.**'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubuserCreditsRequest'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubuserCredits'
examples:
response:
value:
remain: 100
total: 100
used: 0
type: recurring
reset_frequency: monthly
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: type
message: Type should be set to 'recurring', 'nonrecurring',
or 'unlimited'
/v3/subusers/{subuser_name}/credits/remaining:
parameters:
- $ref: '#/components/parameters/UserName'
patch:
operationId: UpdateSubuserRemainingCredit
summary: Update the remaining credits for a Subuser
tags:
- Subusers
description: '**This endpoint allows you to update the remaining credits for
a Subuser.**'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
allocation_update:
type: integer
description: The number of credits to add to or subtract from the
current remaining credits for the Subuser. Use a positive number
to increase the remaining credits or a negative number to reduce
the remaining credits.
required:
- allocation_update
example:
allocation_update: 99
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubuserCredits'
examples:
response:
value:
remain: 100
total: 100
used: 0
type: recurring
reset_frequency: monthly
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: No user found
/v3/subusers/{subuser_name}/ips:
parameters:
- $ref: '#/components/parameters/UserName'
put:
operationId: UpdateSubuserIp
summary: Update IPs assigned to a subuser
tags:
- Subusers
description: "**This endpoint allows you update your subusers' assigned IP.**\n\
\nEach subuser should be assigned to an IP address from which all of this\
\ subuser's mail will be sent. Often, this is the same IP as the parent account,\
\ but each subuser can have one or more of their own IP addresses as well.\
\ \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/)\n\
* [Setup Reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/)"
requestBody:
content:
application/json:
schema:
type: array
description: The IP addresses you would like to assign to the subuser.
items:
type: string
format: ipv4
example:
- 127.0.0.1
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
ips:
type: array
description: The IP addresses that are assigned to the subuser.
items:
type: string
format: ipv4
examples:
response:
value:
ips:
- 127.0.0.1
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
errors:
- field: null
message: authorization required
/v3/subusers/{subuser_name}/stats/monthly:
parameters:
- $ref: '#/components/parameters/UserName'
get:
operationId: ListSubuserMonthlyStat
summary: Retrieve the monthly email statistics for a single subuser
tags:
- Subuser Statistics
description: '**This endpoint allows you to retrive the monthly email statistics
for a specific subuser.**
When using the `sort_by_metric` to sort your stats by a specific metric, you
can not sort by the following metrics:
`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`,
`spam_reports`, or `unsubscribe_drops`.'
parameters:
- name: date
in: query
description: The date of the month to retrieve statistics for. Must be formatted
YYYY-MM-DD
required: true
schema:
type: string
- name: sort_by_metric
in: query
description: 'The metric that you want to sort by. Metrics that you can sort
by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`,
`unique_clicks`, `unique_opens`, and `unsubscribes`.'''
required: false
schema:
type: string
default: delivered
- name: sort_by_direction
in: query
description: The direction you want to sort.
required: false
schema:
type: string
default: desc
$ref: '#/components/schemas/SortByDirection'
- name: limit
in: query
description: Optional field to limit the number of results returned.
required: false
schema:
type: integer
default: 5
- name: offset
in: query
description: Optional beginning point in the list to retrieve from.
required: false
schema:
type: integer
default: 0
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubuserStats'
examples:
response:
value:
date: '2016-02-01'
stats:
- first_name: John
last_name: Doe
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 5
deferred: 0
delivered: 0
invalid_emails: 0
opens: 10
processed: 10
requests: 10
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
name: user1
type: subuser
/v3/subusers/reputations:
get:
operationId: ListReputation
summary: Retrieve Subuser Reputations
tags:
- Subusers
description: '**This endpoint allows you to request the reputations for your
subusers.**
Subuser sender reputations give a good idea how well a sender is doing with
regards to how recipients and recipient servers react to the mail that is
being received. When a bounce, spam report, or other negative action happens
on a sent email, it will affect your sender rating.'
parameters:
- name: usernames
in: query
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
reputation:
type: number
description: The sender reputation this subuser has attained.
username:
type: string
description: The subuser that has this reputation.
required:
- reputation
- username
examples:
response:
value:
- username: example_subuser
reputation: 99
- username: example_subuser2
reputation: 95.2
/v3/subusers/stats:
get:
operationId: ListStat
summary: Retrieve email statistics for your subusers.
tags:
- Subuser Statistics
description: '**This endpoint allows you to retrieve the email statistics for
the given subusers.**
You may retrieve statistics for up to 10 different subusers by including an
additional _subusers_ parameter for each additional subuser.'
parameters:
- name: limit
in: query
description: Limits the number of results returned per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The point in the list to begin retrieving results from.
required: false
schema:
type: integer
- name: aggregated_by
in: query
description: How to group the statistics. Must be either "day", "week", or
"month".
required: false
schema:
type: string
$ref: '#/components/schemas/AggregatedBy'
- name: subusers
in: query
description: The subuser you want to retrieve statistics for. You may include
this parameter up to 10 times to retrieve statistics for multiple subusers.
required: true
schema:
type: string
- name: start_date
in: query
description: The starting date of the statistics to retrieve. Must follow
format YYYY-MM-DD.
required: true
schema:
type: string
- name: end_date
in: query
description: The end date of the statistics to retrieve. Defaults to today.
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CategoryStats'
examples:
response:
value:
- date: '2015-10-01'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-02'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-03'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-04'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-05'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-06'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-07'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-08'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-09'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
- date: '2015-10-10'
stats:
- type: subuser
name: Matt_subuser
metrics:
blocks: 0
bounce_drops: 0
bounces: 0
clicks: 0
deferred: 0
delivered: 0
invalid_emails: 0
opens: 0
processed: 0
requests: 0
spam_report_drops: 0
spam_reports: 0
unique_clicks: 0
unique_opens: 0
unsubscribe_drops: 0
unsubscribes: 0
/v3/subusers/stats/monthly:
get:
operationId: ListMonthlyStat
summary: Retrieve monthly stats for all subusers
tags:
- Subuser Statistics
description: '**This endpoint allows you to retrieve the monthly email statistics
for all subusers over the given date range.**
When using the `s
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_subusers_v3.yaml