{ "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.**\n\nYou can use the `username` query parameter to filter the list for specific subusers.\n\nYou 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": "example@example.com", "id": 1234, "username": "example_subuser" }, { "disabled": false, "email": "example2@example.com", "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": "John@example.com", "email": "John@example.com", "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": "example@example.com", "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.**\n\nThis 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.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.\n", "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.**\n\nSubuser 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. For Regional (EU) subusers, subuser reputation scores will not calculate accurately due to restrictions in place to maintain data residency.", "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.**\n\nYou 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.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`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": "subuser", "in": "query", "description": "A substring search of your subusers.", "required": false, "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", "$ref": "#/components/schemas/SortByMetric" } }, { "name": "sort_by_direction", "in": "query", "description": "The direction you want to sort.", "required": false, "schema": { "type": "string", "default": "desc", "$ref": "#/components/schemas/SortByDirection1" } }, { "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": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 1, "processed": 0, "requests": 100, "spam_report_drops": 0, "spam_reports": 99, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 }, "name": "user1", "type": "subuser" }, { "first_name": "Jane", "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": "user2", "type": "subuser" } ] } } } } } } } } }, "/v3/subusers/stats/sums": { "get": { "operationId": "ListStatSum", "summary": "Retrieve the totals for each email statistic metric for all subusers.", "tags": [ "Subuser Statistics" ], "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**", "parameters": [ { "name": "sort_by_direction", "in": "query", "description": "The direction you want to sort. ", "required": false, "schema": { "type": "string", "default": "desc", "$ref": "#/components/schemas/SortByDirection2" } }, { "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. Must follow format YYYY-MM-DD.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limits the number of results returned per page.", "required": false, "schema": { "type": "integer", "default": 5 } }, { "name": "offset", "in": "query", "description": "The point in the list to begin retrieving results from.", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "aggregated_by", "in": "query", "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", "required": false, "schema": { "type": "string" } }, { "name": "sort_by_metric", "in": "query", "description": "The metric that you want to sort by. Must be a single metric.", "required": false, "schema": { "type": "string", "default": "delivered" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryStats" }, "examples": { "response": { "value": { "date": "2015-10-11", "stats": [ { "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 }, "name": "cat1", "type": "category" }, { "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 }, "name": "cat2", "type": "category" } ] } } } } } } } } } }, "components": { "schemas": { "Subuser": { "title": "List all Subusers for a parent response", "type": "object", "properties": { "disabled": { "type": "boolean", "description": "Whether or not the user is enabled or disabled." }, "id": { "type": "number", "description": "The ID of this subuser." }, "username": { "type": "string", "description": "The name by which this subuser will be referred." }, "email": { "type": "string", "description": "The email address to contact this subuser.", "format": "email" }, "region": { "type": "string", "description": "The region this Subuser is assigned to. This property is returned only if the `include_region` parameter was included and set to `true` in the API request.", "$ref": "#/components/schemas/Region2" } }, "required": [ "disabled", "id", "username", "email" ], "example": { "disabled": false, "email": "example@example.com", "id": 1234, "username": "example_subuser" } }, "SubuserPost": { "title": "Subuser::POST", "type": "object", "properties": { "username": { "type": "string", "description": "The username of the subuser." }, "user_id": { "type": "number", "description": "The user ID for this subuser." }, "email": { "type": "string", "description": "The email address for this subuser.", "format": "email" }, "credit_allocation": { "type": "object", "properties": { "type": { "type": "string" } } }, "region": { "type": "string", "description": "The region this Subuser is assigned to. The property is returned only if the `include_region` parameter is included and set to `true` in the API request.", "default": "global", "$ref": "#/components/schemas/Region3" } }, "required": [ "username", "user_id", "email" ], "example": { "username": "example_subuser", "user_id": 1234, "email": "example@example.com", "credit_allocation": { "type": "unlimited" }, "region": "global" } }, "SubuserCredits": { "title": "Credits of a Subuser", "type": "object", "properties": { "type": { "type": "string", "description": "Type determines how credits are reset for a Subuser. `unlimited` indicates that there is no limit to the Subuser's credits. `recurring` indicates that the credits for the Subuser are reset according to the frequency determined by `reset_frequency`. `nonrecurring` indicates that there is no recurring schedule to reset credits and resets must be done on an ad hoc basis.", "$ref": "#/components/schemas/Type" }, "reset_frequency": { "type": "string", "nullable": true, "description": "The frequency with which a Subuser's credits are reset if `type` is set to `recurring`, otherwise `null`.", "$ref": "#/components/schemas/ResetFrequency" }, "remain": { "type": "integer", "nullable": true, "description": "Total number of remaining credits. `remain` is `null` if the reset `type` for the Subuser's credits is set to `unlimited`.", "minimum": 0 }, "total": { "type": "integer", "nullable": true, "description": "Total number of allowable credits. `total` is `null` if the reset `type` for the Subuser's credits is set to `unlimited` or `nonrecurring`.", "minimum": 0 }, "used": { "type": "integer", "nullable": true, "description": "Total number of used credits. `used` is `null` if the reset `type` for the Subuser's credits is set to `unlimited` or `nonrecurring`.", "minimum": 0 } }, "required": [ "type", "reset_frequency", "remain", "total", "used" ], "example": { "type": "recurring", "reset_frequency": "monthly", "remain": 99, "total": 100, "used": 1 } }, "SubuserCreditsRequest": { "title": "Subuser Credits reset request body", "type": "object", "properties": { "type": { "type": "string", "description": "Type determines how credits are reset for a Subuser. `unlimited` indicates that there is no limit to the Subuser's credits. `recurring` indicates that the credits for the Subuser are reset according to the frequency determined by `reset_frequency`. `nonrecurring` indicates that there is no recurring schedule to reset credits and resets must be done on an ad hoc basis.", "$ref": "#/components/schemas/Type1" }, "reset_frequency": { "type": "string", "description": "The frequency with which a Subuser's credits are reset if `type` is set to `recurring`. Do _not_ include `reset_frequency` if you choose a reset `type` value of `unlimited` or `nonrecurring`.", "$ref": "#/components/schemas/ResetFrequency1" }, "total": { "type": "integer", "description": "Total number of credits to which the Subuser is to be reset. If `type` is `nonrecurring` then the Subuser's credits will be reset to `total` on a one-time basis. If `type` is `recurring` then the Subuser's credits will be reset to `total` every time a reset is scheduled in accordance with the `reset_frequency`. Do _not_ include `total` if you choose a reset `type` value of `unlimited`.", "minimum": 1 } }, "required": [ "type" ] }, "SubuserStats": { "title": "subuser_stats", "type": "object", "properties": { "date": { "type": "string", "description": "The date the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The first name of the subuser." }, "last_name": { "type": "string", "description": "The last name of the subuser." }, "metrics": { "type": "object", "properties": { "blocks": { "type": "integer", "description": "The number of emails that were not allowed to be delivered by ISPs." }, "bounce_drops": { "type": "integer", "description": "The number of emails that were dropped because of a bounce." }, "bounces": { "type": "integer", "description": "The number of emails that bounced instead of being delivered." }, "clicks": { "type": "integer", "description": "The number of links that were clicked in your emails." }, "deferred": { "type": "integer", "description": "The number of emails that temporarily could not be delivered." }, "delivered": { "type": "integer", "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." }, "invalid_emails": { "type": "integer", "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." }, "opens": { "type": "integer", "description": "The total number of times your emails were opened by recipients." }, "processed": { "type": "integer", "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." }, "requests": { "type": "integer", "description": "The number of emails that were requested to be delivered." }, "spam_report_drops": { "type": "integer", "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." }, "spam_reports": { "type": "integer", "description": "The number of recipients who marked your email as spam." }, "unique_clicks": { "type": "integer", "description": "The number of unique recipients who clicked links in your emails." }, "unique_opens": { "type": "integer", "description": "The number of unique recipients who opened your emails." }, "unsubscribe_drops": { "type": "integer", "description": "The number of emails dropped due to a recipient unsubscribing from your emails." }, "unsubscribes": { "type": "integer", "description": "The number of recipients who unsubscribed from your emails." } } }, "name": { "type": "string", "description": "The username of the subuser." }, "type": { "type": "string", "description": "The type of account." } } } } }, "example": { "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" } ] } }, "CategoryStats": { "title": "Stats: Category Stats", "type": "object", "properties": { "date": { "type": "string", "description": "The date the statistics were gathered." }, "stats": { "type": "array", "items": { "type": "object", "properties": { "metrics": { "type": "object", "properties": { "blocks": { "type": "integer", "description": "The number of emails that were not allowed to be delivered by ISPs." }, "bounce_drops": { "type": "integer", "description": "The number of emails that were dropped because of a bounce." }, "bounces": { "type": "integer", "description": "The number of emails that bounced instead of being delivered." }, "clicks": { "type": "integer", "description": "The number of links that were clicked." }, "deferred": { "type": "integer", "description": "The number of emails that temporarily could not be delivered." }, "delivered": { "type": "integer", "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." }, "invalid_emails": { "type": "integer", "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." }, "opens": { "type": "integer", "description": "The total number of times your emails were opened by recipients." }, "processed": { "type": "integer", "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." }, "requests": { "type": "integer", "description": "The number of emails that were requested to be delivered." }, "spam_report_drops": { "type": "integer", "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." }, "spam_reports": { "type": "integer", "description": "The number of recipients who marked your email as spam." }, "unique_clicks": { "type": "integer", "description": "The number of unique recipients who clicked links in your emails." }, "unique_opens": { "type": "integer", "description": "The number of unique recipients who opened your emails." }, "unsubscribe_drops": { "type": "integer", "description": "The number of emails dropped due to a recipient unsubscribing from your emails." }, "unsubscribes": { "type": "integer", "description": "The number of recipients who unsubscribed from your emails." } }, "required": [ "blocks", "bounce_drops", "bounces", "clicks", "deferred", "delivered", "invalid_emails", "opens", "processed", "requests", "spam_report_drops", "spam_reports", "unique_clicks", "unique_opens", "unsubscribe_drops", "unsubscribes" ] }, "name": { "type": "string", "description": "The name of the category." }, "type": { "type": "string", "description": "How you are segmenting your statistics." } }, "required": [ "type" ] } } }, "required": [ "date" ], "example": { "date": "2015-01-01", "stats": [ { "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 }, "name": "cat1", "type": "category" }, { "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 }, "name": "cat2", "type": "category" } ] } }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "An error message." }, "field": { "description": "When applicable, this property value will be the field that generated the error.", "nullable": true, "type": "string" }, "help": { "type": "object", "description": "When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error." } } } }, "id": { "type": "string", "description": "When applicable, this property value will be an error ID." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } }, "Region": { "type": "string", "enum": [ "all", "global", "eu" ] }, "Region1": { "type": "string", "enum": [ "global", "eu" ] }, "SortByDirection": { "type": "string", "enum": [ "desc", "asc" ] }, "AggregatedBy": { "type": "string", "enum": [ "day", "week", "month" ] }, "SortByMetric": { "type": "string", "enum": [ "blocks", "bounces", "clicks", "delivered", "opens", "requests", "unique_clicks", "unique_opens", "unsubscribes" ] }, "SortByDirection1": { "type": "string", "enum": [ "desc", "asc" ] }, "SortByDirection2": { "type": "string", "enum": [ "desc", "asc" ] }, "Region2": { "type": "string", "enum": [ "global", "eu" ] }, "Region3": { "type": "string", "enum": [ "global", "eu" ] }, "Type": { "type": "string", "enum": [ "unlimited", "recurring", "nonrecurring" ] }, "ResetFrequency": { "type": "string", "enum": [ "monthly", "weekly", "daily" ] }, "Type1": { "type": "string", "enum": [ "unlimited", "recurring", "nonrecurring" ] }, "ResetFrequency1": { "type": "string", "enum": [ "monthly", "weekly", "daily" ] } }, "responses": {}, "parameters": { "PaginationCommonOffset": { "name": "offset", "in": "query", "required": false, "description": "The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "UserName": { "name": "subuser_name", "in": "path", "required": true, "description": "The username of the Subuser.", "schema": { "type": "string" } } }, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header." } } }, "tags": [ { "name": "Subusers", "description": "Twilio SendGrid Subusers API" }, { "name": "Subuser Statistics", "description": "Twilio SendGrid Subusers API: Statistics Operations" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }