diff --git a/CHANGELOG.md b/CHANGELOG.md index 874c1da..e842d6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ # Change Log All notable changes to this project will be documented in this file. +## [1.1.10] - 2016-06-27 +### Added +- v3 /mail/send out of beta + ## [1.0.10] - 2016-06-09 ### Fixed - Remove unecessary test diff --git a/oai.json b/oai.json index 9d978e8..42b80d3 100644 --- a/oai.json +++ b/oai.json @@ -1764,6 +1764,33 @@ "title": "Create monitor settings request", "type": "object" }, + "parse-setting": { + "example": { + "hostname": "myhostname.com", + "send_raw": true, + "spam_check": false, + "url": "http://email.myhostname.com" + }, + "properties": { + "hostname": { + "description": "A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, parse.yourdomain.com.", + "type": "string" + }, + "send_raw": { + "description": "Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to \"false\", SendGrid will send a JSON payload of the content of your email. ", + "type": "boolean" + }, + "spam_check": { + "description": "Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain.", + "type": "boolean" + }, + "url": { + "description": "The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL.", + "type": "string" + } + }, + "type": "object" + }, "partner_settings_new_relic": { "properties": { "enable_subuser_statistics": { @@ -2257,36 +2284,47 @@ }, "properties": { "address": { + "description": "The street address for this user profile.", "type": "string" }, "address2": { + "description": "An optional second line for the street address of this user profile.", "type": "string" }, "city": { + "description": "The city for the user profile.", "type": "string" }, "company": { + "description": "That company that this user profile is associated with.", "type": "string" }, "country": { + "description": "Th country of this user profile.", "type": "string" }, "first_name": { + "description": "The first name of the user.", "type": "string" }, "last_name": { + "description": "The last name of the user.", "type": "string" }, "phone": { + "description": "The phone number for the user.", "type": "string" }, "state": { + "description": "The state for this user.", "type": "string" }, "website": { + "description": "The website associated with this user.", "type": "string" }, "zip": { + "description": "The zip code for this user.", "type": "string" } }, @@ -2673,12 +2711,20 @@ "title": "SendGrid V3 API", "version": "3.0" }, + "parameters": { + "trait:authorizationHeader:Authorization": { + "default": "Bearer <>", + "description": "", + "in": "header", + "name": "Authorization", + "required": true, + "type": "string" + } + }, "paths": { "/access_settings/activity": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "GET_access_settings-activity", "parameters": [ @@ -2706,14 +2752,6 @@ "ip": "1.1.1.1", "last_at": 1444406672, "location": "Australia" - }, - { - "allowed": false, - "auth_method": "basic", - "first_at": 1444087505, - "ip": "1.2.3.48", - "last_at": 1444087505, - "location": "Mukilteo, Washington" } ] } @@ -2721,50 +2759,32 @@ "schema": { "properties": { "result": { - "description": "An array containing the IPs that recently attempted to access your account.", "items": { "properties": { "allowed": { - "description": "Indicates if the IP address was granted access to the account.", "type": "boolean" }, "auth_method": { - "description": "The authentication method used when attempting access.", "type": "string" }, "first_at": { - "description": "A Unix timestamp indicating when the first access attempt was made.", "type": "integer" }, "ip": { - "description": "The IP addressed used during the access attempt.", "type": "string" }, "last_at": { - "description": "A Unix timestamp indicating when the most recent access attempt was made", "type": "integer" }, "location": { - "description": "The geographic location from which the access attempt originated.", "type": "string" } }, - "required": [ - "allowed", - "auth_method", - "first_at", - "ip", - "last_at", - "location" - ], "type": "object" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -2813,11 +2833,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -2828,9 +2844,7 @@ "summary": "Remove one or more IPs from the whitelist" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "GET_access_settings-whitelist", "parameters": [], @@ -2848,18 +2862,6 @@ "id": 1, "ip": "192.168.1.1/32", "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 2, - "ip": "192.168.1.2/32", - "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 3, - "ip": "192.168.1.3/32", - "updated_at": 1441824715 } ] } @@ -2867,40 +2869,26 @@ "schema": { "properties": { "result": { - "description": "An array listing all of your whitelisted IPs.", "items": { "properties": { "created_at": { - "description": "A Unix timestamp indicating when the IP was whitelisted.", "type": "integer" }, "id": { - "description": "The ID of the whitelisted IP.", "type": "integer" }, "ip": { - "description": "The whitelisted IP.", "type": "string" }, "updated_at": { - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated.", "type": "integer" } }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ], "type": "object" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -2976,18 +2964,6 @@ "id": 1, "ip": "192.168.1.1/32", "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 2, - "ip": "192.0.0.0/8", - "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 3, - "ip": "192.168.1.3/32", - "updated_at": 1441824715 } ] } @@ -2995,40 +2971,26 @@ "schema": { "properties": { "result": { - "description": "An array listing all of your whitelisted IPs.", "items": { "properties": { "created_at": { - "description": "A Unix timestamp indicating when the IP was whitelisted.", "type": "integer" }, "id": { - "description": "The ID of the whitelisted IP.", "type": "integer" }, "ip": { - "description": "The whitelisted IP.", "type": "string" }, "updated_at": { - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated.", "type": "integer" } }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ], "type": "object" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -3043,28 +3005,14 @@ }, "/access_settings/whitelist/{rule_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a specific IP address from your IP whitelist.**\n\nWhen removing a specific IP address from your whitelist, you must include the ID in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "DELETE_access_settings-whitelist-rule_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -3075,9 +3023,7 @@ "summary": "Remove a specific IP from the whitelist" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retreive a specific IP address that has been whitelisted.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "GET_access_settings-whitelist-rule_id", "parameters": [], @@ -3098,28 +3044,18 @@ "schema": { "properties": { "created_at": { - "description": "A Unix timestamp indicating when the IP was whitelisted.", "type": "integer" }, "id": { - "description": "The ID of the IP address.", "type": "integer" }, "ip": { - "description": "The IP address.", "type": "string" }, "updated_at": { - "description": "A Unix timestamp indicating when the IP address was last updated.", "type": "integer" } }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ], "type": "object" } } @@ -3141,14 +3077,377 @@ } ] }, - "/api_keys": { + "/alerts": { + "get": { + "consumes": [], + "description": "**This endpoint allows you to retieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "GET_alerts", + "parameters": [ + { + "description": "", + "in": "header", + "name": "Authorization", + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ + { + "created_at": 1451498784, + "email_to": "reaper@example.com", + "id": 46, + "percentage": 90, + "type": "usage_limit", + "updated_at": 1451498784 + }, + { + "created_at": 1451498812, + "email_to": "reaper@example.com", + "frequency": "monthly", + "id": 47, + "type": "stats_notification", + "updated_at": 1451498812 + }, + { + "created_at": 1451520930, + "email_to": "someone@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451520930 + } + ] + }, + "schema": { + "description": "The list of alerts.", + "items": { + "properties": { + "created_at": { + "description": "A Unix timestamp indicating when the alert was created.", + "type": "integer" + }, + "email_to": { + "description": "The email address that the alert will be sent to.", + "type": "string" + }, + "frequency": { + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\".", + "type": "string" + }, + "id": { + "description": "The ID of the alert.", + "type": "integer" + }, + "percentage": { + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.", + "type": "integer" + }, + "type": { + "description": "The type of alert.", + "enum": [ + "usage_limit", + "stats_notification" + ], + "type": "string" + }, + "updated_at": { + "description": "A Unix timestamp indicating when the alert was last modified.", + "type": "integer" + } + }, + "required": [ + "created_at", + "email_to", + "id", + "type" + ], + "type": "object" + }, + "type": "array" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve all alerts", + "tags": [ + "Alerts" + ] + }, + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "POST_alerts", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "example": { + "email_to": "eric.schallock@sendgrid.com", + "frequency": "daily", + "type": "stats_notification" + }, + "properties": { + "email_to": { + "description": "The email address the alert will be sent to.\nExample: test@example.com", + "type": "string" + }, + "frequency": { + "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily", + "type": "string" + }, + "percentage": { + "description": "Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90", + "type": "integer" + }, + "type": { + "description": "The type of alert you want to create. Can be either usage_alert or stats_notification.\nExample: usage_alert", + "type": "string" + } + }, + "required": [ + "type", + "email_to" + ], + "type": "object" + } + }, + { + "description": "", + "in": "header", + "name": "Authorization", + "type": "string" + } + ], + "produces": [ + "application/json", + "text/plain" + ], + "responses": { + "201": { + "description": "", + "examples": { + "text/plain": { + "created_at": 1465595735, + "email_to": "eric.schallock@sendgrid.com", + "frequency": "daily", + "id": 304575, + "type": "stats_notification", + "updated_at": 1465595735 + } + }, + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Create a new Alert", + "tags": [ + "Alerts" + ] + } + }, + "/alerts/{alert_id}": { + "delete": { + "consumes": [], + "description": "**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "DELETE_alerts-alert_id", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Delete an alert" + }, "get": { + "consumes": [], + "description": "**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "GET_alerts-alert_id", + "parameters": [ + { + "description": "", + "in": "header", + "name": "Authorization", + "type": "string" + } + ], + "produces": [ + "application/json", + "text/plain" + ], + "responses": { + "200": { + "description": "", + "examples": { + "text/plain": { + "created_at": 1465613735, + "email_to": "eric.schallock@sendgrid.com", + "frequency": "daily", + "id": 304575, + "type": "stats_notification", + "updated_at": 1465595735 + } + }, + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve a specific alert" + }, + "parameters": [ + { + "description": "The ID of the alert you would like to retrieve.", + "in": "path", + "name": "alert_id", + "required": true, + "type": "integer" + } + ], + "patch": { "consumes": [ "application/json" ], + "description": "**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "PATCH_alerts-alert_id", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "example": { + "email_to": "test@example.com" + }, + "properties": { + "email_to": { + "description": "The new email address you want your alert to be sent to.\nExample: test@example.com", + "type": "string" + }, + "frequency": { + "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly", + "type": "string" + }, + "percentage": { + "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90", + "type": "integer" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "created_at": 1451520930, + "email_to": "test@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451522691 + } + }, + "schema": { + "properties": { + "created_at": { + "description": "A Unix timestamp indicating when the alert was created.", + "type": "integer" + }, + "email_to": { + "description": "The email address that the alert will be sent to.", + "type": "string" + }, + "frequency": { + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\".", + "type": "string" + }, + "id": { + "description": "The ID of the alert.", + "type": "integer" + }, + "percentage": { + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.", + "type": "integer" + }, + "type": { + "description": "The type of alert.", + "enum": [ + "usage_alert", + "stats_notification" + ], + "type": "string" + }, + "updated_at": { + "description": "A Unix timestamp indicating when the alert was last modified.", + "type": "integer" + } + }, + "required": [ + "created_at", + "email_to", + "id", + "type", + "updated_at" + ], + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Update an alert" + } + }, + "/api_keys": { + "get": { + "consumes": [], "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).", "operationId": "GET_api_keys", - "parameters": [], + "parameters": [ + { + "in": "query", + "name": "limit", + "type": "integer" + } + ], "produces": [ "application/json" ], @@ -3219,6 +3518,7 @@ "schema": { "example": { "name": "My API Key", + "sample": "data", "scopes": [ "mail.send", "alerts.create", @@ -3230,6 +3530,9 @@ "description": "The name you will use to describe this API Key.", "type": "string" }, + "sample": { + "type": "string" + }, "scopes": { "description": "The individual permissions that you are giving to this API Key.", "items": { @@ -3338,25 +3641,15 @@ "Authorization": [] } ], - "summary": "Create API keys" - } - }, - "/api_keys/{api_key_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "**This endpoint allows you to revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|", - "operationId": "DELETE_api_keys-api_key_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "summary": "Create API keys" + } + }, + "/api_keys/{api_key_id}": { + "delete": { + "consumes": [], + "description": "**This endpoint allows you to revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|", + "operationId": "DELETE_api_keys-api_key_id", + "parameters": [], "produces": [ "application/json" ], @@ -3395,9 +3688,7 @@ "summary": "Delete API keys" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single api key.**\n\nIf the API Key ID does not exist an HTTP 404 will be returned.", "operationId": "GET_api_keys-api_key_id", "parameters": [], @@ -3647,10 +3938,8 @@ }, "/asm/groups": { "get": { - "consumes": [ - "application/json" - ], - "description": "**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.", + "consumes": [], + "description": "**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).\n\nSuppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content.", "operationId": "GET_asm-groups", "parameters": [ { @@ -3801,20 +4090,10 @@ }, "/asm/groups/{group_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a suppression group.**\n\nYou can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the \"one-click unsubscribe\" option on an email associated with a deleted group, that recipient will be added to the global suppression list.\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", "operationId": "DELETE_asm-groups-group_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -3834,9 +4113,7 @@ "summary": "Delete a suppression group." }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", "operationId": "GET_asm-groups-group_id", "parameters": [], @@ -3857,19 +4134,32 @@ } }, "schema": { - "allOf": [ - { - "$ref": "#/definitions/suppression_group" + "properties": { + "description": { + "description": "The description of the suppression group.", + "type": "string" }, - { - "properties": { - "unsubscribes": { - "description": "The unsubscribes associated with this group.", - "type": "integer" - } - } + "id": { + "description": "The ID of the suppression group.", + "type": "integer" + }, + "is_default": { + "description": "Indicates if this is the default suppression group.", + "type": "boolean" + }, + "last_email_sent_at": { + "description": "A unix timestamp indicating the last time this group was assigned to an email.", + "type": "null" + }, + "name": { + "description": "The name of the suppression group.", + "type": "string" + }, + "unsubscribes": { + "description": "The number of unsubscribes, or suppressions, in this group.", + "type": "integer" } - ], + }, "type": "object" } } @@ -3914,7 +4204,7 @@ }, "id": { "description": "The id of the suppression group.", - "type": "number" + "type": "integer" }, "is_default": { "description": "Indicates if the suppression group is set as the default group.", @@ -3956,9 +4246,7 @@ }, "/asm/groups/{group_id}/suppressions": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", "operationId": "GET_asm-groups-group_id-suppressions", "parameters": [], @@ -3992,7 +4280,7 @@ }, "parameters": [ { - "description": "The id of the suppression group that you are retrieving email addresses from.", + "description": "The id of the unsubscribe group that you are adding suppressions to.", "in": "path", "name": "group_id", "required": true, @@ -4071,28 +4359,78 @@ "summary": "Add suppressions to a suppression group" } }, - "/asm/groups/{group_id}/suppressions/{email}": { - "delete": { + "/asm/groups/{group_id}/suppressions/search": { + "parameters": [ + { + "description": "The ID of the suppression group that you would like to search.", + "in": "path", + "name": "group_id", + "required": true, + "type": "string" + } + ], + "post": { "consumes": [ "application/json" ], - "description": "**This endpoint allows you to remove a suppressed email address from the given suppression group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", - "operationId": "DELETE_asm-groups-group_id-suppressions-email", + "description": "**This endpoint allows you to search a suppression group for multiple suppressions.**\n\nWhen given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", + "operationId": "POST_asm-groups-group_id-suppressions-search", "parameters": [ { "in": "body", "name": "body", "schema": { - "type": "null" + "example": { + "recipient_emails": [ + "exists1@example.com", + "exists2@example.com", + "doesnotexists@example.com" + ] + }, + "properties": { + "recipient_emails": { + "description": "The list of email address that you want to search the suppression group for.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "recipient_emails" + ], + "type": "object" } } ], - "produces": [], + "produces": [ + "application/json" + ], "responses": { - "204": { + "200": { "description": "", + "examples": { + "application/json": { + "recipient_emails": [ + "exists1@example.com", + "exists2@example.com" + ] + } + }, "schema": { - "type": "null" + "properties": { + "recipient_emails": { + "description": "The email address from your search that do exist in the suppression group.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "recipient_emails" + ], + "type": "object" } } }, @@ -4101,6 +4439,26 @@ "Authorization": [] } ], + "summary": "Search for suppressions within a group" + } + }, + "/asm/groups/{group_id}/suppressions/{email}": { + "delete": { + "consumes": [], + "description": "**This endpoint allows you to remove a suppressed email address from the given suppression group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", + "operationId": "DELETE_asm-groups-group_id-suppressions-email", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ], "summary": "Delete a suppression from a suppression group" }, "parameters": [ @@ -4125,7 +4483,7 @@ "consumes": [ "application/json" ], - "description": "**This endpoint allows you to retrieve a list of all suppressions.**\n\nSuppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.", + "description": "**This endpoint allows you to retrieve a list of all suppressions.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", "operationId": "GET_asm-suppressions", "parameters": [], "produces": [ @@ -4276,27 +4634,14 @@ }, "/asm/suppressions/global/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "DELETE_asm-suppressions-global-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -4310,9 +4655,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "GET_asm-suppressions-global-email", "parameters": [], @@ -4349,7 +4692,7 @@ }, "parameters": [ { - "description": "The email address you want to remove from the global suppressions group.", + "description": "The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.", "in": "path", "name": "email", "required": true, @@ -4362,7 +4705,7 @@ "consumes": [ "application/json" ], - "description": "**This endpoint will return a list of all suppression groups, indicating if the given email address is suppressed for each group.**\n\nSuppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.", + "description": "**This endpoint returns the list of all groups that the given email address has been unsubscribed from.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", "operationId": "GET_asm-suppressions-email", "parameters": [], "produces": [ @@ -4466,9 +4809,7 @@ }, "/browsers/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by browser type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_browsers-stats", "parameters": [ @@ -4594,9 +4935,7 @@ }, "/campaigns": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "GET_campaigns", "parameters": [ @@ -4605,14 +4944,14 @@ "description": "The number of results you would like to receive at a time.", "in": "query", "name": "limit", - "type": "number" + "type": "integer" }, { "default": 0, "description": "The index of the first campaign to return, where 0 is the first campaign.", "in": "query", "name": "offset", - "type": "number" + "type": "integer" } ], "produces": [ @@ -4633,8 +4972,7 @@ "id": 986724, "ip_pool": "marketing", "list_ids": [ - 110, - 124 + 110 ], "plain_content": "Check out our spring line!", "segment_ids": [ @@ -4645,28 +4983,6 @@ "subject": "New Products for Spring!", "suppression_group_id": 42, "title": "March Newsletter" - }, - { - "categories": [ - "winter line" - ], - "custom_unsubscribe_url": "", - "html_content": "

Last call for winter clothes!

", - "id": 986723, - "ip_pool": "marketing", - "list_ids": [ - 110, - 124 - ], - "plain_content": "Last call for winter clothes!", - "segment_ids": [ - 110 - ], - "sender_id": 124451, - "status": "Sent", - "subject": "Final Winter Product Sale!", - "suppression_group_id": 42, - "title": "February Newsletter" } ] } @@ -4675,7 +4991,57 @@ "properties": { "result": { "items": { - "$ref": "#/definitions/campaign_response" + "properties": { + "categories": { + "items": { + "type": "string" + }, + "type": "array" + }, + "custom_unsubscribe_url": { + "type": "string" + }, + "html_content": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "ip_pool": { + "type": "string" + }, + "list_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "plain_content": { + "type": "string" + }, + "segment_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "sender_id": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "suppression_group_id": { + "type": "integer" + }, + "title": { + "type": "string" + } + }, + "type": "object" }, "type": "array" } @@ -4852,20 +5218,10 @@ }, "/campaigns/{campaign_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "DELETE_campaigns-campaign_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -4907,9 +5263,7 @@ "summary": "Delete a Campaign" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "GET_campaigns-campaign_id", "parameters": [], @@ -4929,8 +5283,7 @@ "id": 986724, "ip_pool": "marketing", "list_ids": [ - 110, - 124 + 110 ], "plain_content": "Check out our spring line!", "segment_ids": [ @@ -4944,7 +5297,57 @@ } }, "schema": { - "$ref": "#/definitions/campaign_response" + "properties": { + "categories": { + "items": { + "type": "string" + }, + "type": "array" + }, + "custom_unsubscribe_url": { + "type": "string" + }, + "html_content": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "ip_pool": { + "type": "string" + }, + "list_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "plain_content": { + "type": "string" + }, + "segment_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "sender_id": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "suppression_group_id": { + "type": "integer" + }, + "title": { + "type": "string" + } + }, + "type": "object" } }, "401": { @@ -4989,7 +5392,7 @@ }, "parameters": [ { - "description": "The ID of the campaign that you would like to delete.", + "description": "The id of the campaign you would like to retrieve.", "in": "path", "name": "campaign_id", "required": true, @@ -5210,20 +5613,10 @@ }, "/campaigns/{campaign_id}/schedules": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "DELETE_campaigns-campaign_id-schedules", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -5287,9 +5680,7 @@ "summary": "Unschedule a Scheduled Campaign" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "GET_campaigns-campaign_id-schedules", "parameters": [], @@ -5647,20 +6038,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to immediately send a campaign at the time you make the API call.**\n\nNormally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "POST_campaigns-campaign_id-schedules-now", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -5895,9 +6276,7 @@ }, "/categories": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all of your categories.**\n\nCategories can help organize your email analytics by enabling you to \u201ctag\u201d emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).", "operationId": "GET_categories", "parameters": [ @@ -6007,9 +6386,7 @@ }, "/categories/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). ", "operationId": "GET_categories-stats", "parameters": [ @@ -6193,9 +6570,7 @@ }, "/categories/stats/sums": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). ", "operationId": "GET_categories-stats-sums", "parameters": [ @@ -6409,9 +6784,7 @@ }, "/clients/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_clients-stats", "parameters": [ @@ -6500,9 +6873,7 @@ }, "/clients/{client_type}/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Client Types\n- phone\n- tablet\n- webmail\n- desktop\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_clients-client_type-stats", "parameters": [ @@ -6602,9 +6973,7 @@ }, "/contactdb/custom_fields": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all custom fields.** \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-custom_fields", "parameters": [], @@ -6781,20 +7150,10 @@ }, "/contactdb/custom_fields/{custom_field_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "DELETE_contactdb-custom_fields-custom_field_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -6868,9 +7227,7 @@ "summary": "Delete a Custom Field" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-custom_fields-custom_field_id", "parameters": [], @@ -6974,7 +7331,7 @@ 4 ], "items": { - "type": "number" + "type": "integer" }, "type": "array" } @@ -7034,9 +7391,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-lists", "parameters": [], @@ -7183,9 +7538,7 @@ }, "/contactdb/lists/{list_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific recipient list with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-lists-list_id", "parameters": [ @@ -7198,13 +7551,6 @@ "in": "query", "name": "delete_contacts", "type": "boolean" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [ @@ -7277,9 +7623,7 @@ "summary": "Delete a List" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "This endpoint allows you to retrieve a single recipient list.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-lists-list_id", "parameters": [ @@ -7287,7 +7631,7 @@ "description": "The ID of the list to retrieve.", "in": "query", "name": "list_id", - "type": "number" + "type": "integer" } ], "produces": [ @@ -7382,7 +7726,7 @@ "in": "query", "name": "list_id", "required": true, - "type": "number" + "type": "integer" }, { "in": "body", @@ -7456,9 +7800,7 @@ }, "/contactdb/lists/{list_id}/recipients": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all recipients on the list with the given ID.** \n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-lists-list_id-recipients", "parameters": [ @@ -7481,7 +7823,7 @@ "in": "query", "name": "list_id", "required": true, - "type": "number" + "type": "integer" } ], "produces": [ @@ -7723,9 +8065,7 @@ }, "/contactdb/lists/{list_id}/recipients/{recipient_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a single recipient from a list.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-lists-list_id-recipients-recipient_id", "parameters": [ @@ -7734,21 +8074,14 @@ "in": "query", "name": "list_id", "required": true, - "type": "number" + "type": "integer" }, { "description": "The ID of the recipient to take off the list.", "in": "query", "name": "recipient_id", "required": true, - "type": "number" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } + "type": "integer" } ], "produces": [ @@ -7842,20 +8175,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to add a single recipient to a list.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "POST_contactdb-lists-list_id-recipients-recipient_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -8007,9 +8330,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**\n\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients", "parameters": [ @@ -8204,6 +8525,9 @@ ], "items": { "properties": { + "age": { + "type": "integer" + }, "email": { "description": "The email address of the recipient.", "format": "email", @@ -8305,9 +8629,7 @@ }, "/contactdb/recipients/billable_count": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**\n\nYou are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients-billable_count", "parameters": [], @@ -8354,9 +8676,7 @@ }, "/contactdb/recipients/count": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-recipients-count", "parameters": [], @@ -8406,9 +8726,7 @@ }, "/contactdb/recipients/search": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 02 Feb 2015 23:59:59 GMT.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-recipients-search", "parameters": [ @@ -8416,6 +8734,11 @@ "in": "query", "name": "{field_name}", "type": "string" + }, + { + "in": "query", + "name": "%7Bfield_name%7D", + "type": "string" } ], "produces": [ @@ -8510,20 +8833,10 @@ }, "/contactdb/recipients/{recipient_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a single recipient with the given ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-recipients-recipient_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -8591,9 +8904,7 @@ "summary": "Delete a Recipient" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single recipient by ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients-recipient_id", "parameters": [], @@ -8655,9 +8966,7 @@ }, "/contactdb/recipients/{recipient_id}/lists": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the lists that a given recipient belongs to.**\n\nEach recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients-recipient_id-lists", "parameters": [], @@ -8758,9 +9067,7 @@ }, "/contactdb/reserved_fields": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-reserved_fields", "parameters": [], @@ -8857,9 +9164,7 @@ }, "/contactdb/segments": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your segments.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "GET_contactdb-segments", "parameters": [], @@ -9104,9 +9409,7 @@ }, "/contactdb/segments/{segment_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a segment from your recipients database.**\n\nYou also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "DELETE_contactdb-segments-segment_id", "parameters": [ @@ -9115,13 +9418,6 @@ "in": "query", "name": "delete_contacts", "type": "boolean" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [ @@ -9195,9 +9491,7 @@ "summary": "Delete a segment" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single segment with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "GET_contactdb-segments-segment_id", "parameters": [ @@ -9206,7 +9500,7 @@ "in": "query", "name": "segment_id", "required": true, - "type": "number" + "type": "integer" } ], "produces": [ @@ -9460,9 +9754,7 @@ }, "/contactdb/segments/{segment_id}/recipients": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "GET_contactdb-segments-segment_id-recipients", "parameters": [ @@ -9572,9 +9864,7 @@ }, "/devices/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_devices-stats", "parameters": [ @@ -10049,9 +10339,7 @@ }, "/geo/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by country and state/province.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_geo-stats", "parameters": [ @@ -10600,9 +10888,7 @@ }, "/ips": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all assigned and unassigned IPs.**\n\nResponse includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "GET_ips", "parameters": [ @@ -10738,9 +11024,7 @@ }, "/ips/assigned": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve only assigned IP addresses.**\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "GET_ips-assigned", "parameters": [], @@ -10812,9 +11096,7 @@ }, "/ips/pools": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retreive all of your IP pools.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "GET_ips-pools", "parameters": [], @@ -10910,20 +11192,10 @@ }, "/ips/pools/{pool_name}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete an IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "DELETE_ips-pools-pool_name", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -10960,9 +11232,7 @@ "summary": "Delete an IP pool." }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to list all of the IP addresses that are in a specific IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "GET_ips-pools-pool_name", "parameters": [], @@ -11252,20 +11522,10 @@ }, "/ips/pools/{pool_name}/ips/{ip}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an IP address from an IP pool.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "DELETE_ips-pools-pool_name-ips-ip", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -11320,9 +11580,7 @@ }, "/ips/warmup": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "GET_ips-warmup", "parameters": [], @@ -11446,20 +11704,10 @@ }, "/ips/warmup/{ip_address}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "DELETE_ips-warmup-ip_address", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -11513,9 +11761,7 @@ "summary": "Remove an IP from warmup" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the warmup status for a specific IP address.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "GET_ips-warmup-ip_address", "parameters": [], @@ -11583,9 +11829,7 @@ }, "/ips/{ip_address}": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to see which IP pools a particular IP address has been added to.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "GET_ips-ip_address", "parameters": [], @@ -11684,20 +11928,10 @@ "/mail/batch": { "parameters": [], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.**\n\nIf you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", "operationId": "POST_mail-batch", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -11743,9 +11977,7 @@ }, "/mail/batch/{batch_id}": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate a batch ID.**\n\nIf you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", "operationId": "GET_mail-batch-batch_id", "parameters": [], @@ -11813,14 +12045,14 @@ } ] }, - "/mail/send/beta": { + "/mail/send": { "parameters": [], "post": { "consumes": [ "application/json" ], "description": "This endpoint allows you to send email over SendGrid\u2019s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n* Top level parameters are referred to as \"global\".\n* Individual fields within the personalizations array will override any other global, or \u201cmessage level\u201d, parameters that are defined outside of personalizations.\n\nFor an overview of the v3 Mail Send endpoint, please visit our [v3 API Reference](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html)\n\nFor more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html).", - "operationId": "POST_mail-send-beta", + "operationId": "POST_mail-send", "parameters": [ { "in": "body", @@ -11853,7 +12085,7 @@ "content": [ { "type": "text/html", - "value": "

Hello, world!

" + "value": "

Hello, world!

" } ], "custom_args": { @@ -11915,13 +12147,8 @@ "send_at": 1409348513, "subject": "Hello, World!", "substitutions": { - "sub": { - "%name%": [ - "John", - "Jane", - "Sam" - ] - } + "id": "substitutions", + "type": "object" }, "to": [ { @@ -12242,7 +12469,7 @@ ], "type": "object" }, - "maxItems": 100, + "maxItems": 1000, "type": "array", "uniqueItems": false }, @@ -12362,7 +12589,6 @@ "required": [ "personalizations", "from", - "reply_to", "subject", "content" ], @@ -12405,7 +12631,7 @@ "Authorization": [] } ], - "summary": "v3 Mail Send Beta", + "summary": "v3 Mail Send", "tags": [ "Mail Send" ] @@ -12413,9 +12639,7 @@ }, "/mail_settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all mail settings.**\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings", "parameters": [ @@ -12556,9 +12780,7 @@ }, "/mail_settings/address_whitelist": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current email address whitelist settings.**\n\nThe address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain \u201cexample.com,\u201d and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-address_whitelist", "parameters": [], @@ -12653,9 +12875,7 @@ }, "/mail_settings/bcc": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current BCC mail settings.**\n\nWhen the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-bcc", "parameters": [], @@ -12730,9 +12950,7 @@ }, "/mail_settings/bounce_purge": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current bounce purge settings.**\n\nThis setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-bounce_purge", "parameters": [], @@ -12810,9 +13028,7 @@ }, "/mail_settings/footer": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Footer mail settings.**\n\nThe footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-footer", "parameters": [], @@ -12890,9 +13106,7 @@ }, "/mail_settings/forward_bounce": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current bounce forwarding mail settings.**\n\nActivating this setting allows you to specify an email address to which bounce reports are forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-forward_bounce", "parameters": [], @@ -12967,9 +13181,7 @@ }, "/mail_settings/forward_spam": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Forward Spam mail settings.**\n\nEnabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-forward_spam", "parameters": [], @@ -13044,9 +13256,7 @@ }, "/mail_settings/plain_content": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Plain Content mail settings.**\n\nThe plain content setting will automatically convert any plain text emails that you send to HTML before sending.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-plain_content", "parameters": [], @@ -13136,9 +13346,7 @@ }, "/mail_settings/spam_check": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Spam Checker mail settings.**\n\nThe spam checker filter notifies you when emails are detected that exceed a predefined spam threshold.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-spam_check", "parameters": [], @@ -13233,9 +13441,7 @@ }, "/mail_settings/template": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-template", "parameters": [], @@ -13308,12 +13514,18 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if the legacy email template mail setting is enabled.", "type": "boolean" }, "html_content": { + "description": "The HTML content of your legacy email template.", "type": "string" } }, + "required": [ + "enabled", + "html_content" + ], "type": "object" } } @@ -13328,9 +13540,7 @@ }, "/mailbox_providers/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_mailbox_providers-stats", "parameters": [ @@ -14062,9 +14272,7 @@ }, "/partner_settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all partner settings that you can enable.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).", "operationId": "GET_partner_settings", "parameters": [ @@ -14147,9 +14355,7 @@ }, "/partner_settings/new_relic": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html).", "operationId": "GET_partner_settings-new_relic", "parameters": [], @@ -14241,9 +14447,7 @@ }, "/scopes": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys can be used to authenticate the use of [SendGrid\u2019s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). ", "operationId": "GET_scopes", "parameters": [], @@ -14335,9 +14539,7 @@ }, "/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your global email statistics between a given date range.**\n\nParent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.", "operationId": "GET_stats", "parameters": [ @@ -14677,9 +14879,7 @@ }, "/subusers": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", "operationId": "GET_subusers", "parameters": [ @@ -14693,13 +14893,13 @@ "description": "The number of results you would like to get in each request.", "in": "query", "name": "limit", - "type": "number" + "type": "integer" }, { "description": "The number of subusers to skip.", "in": "query", "name": "offset", - "type": "number" + "type": "integer" } ], "produces": [ @@ -14912,9 +15112,7 @@ }, "/subusers/reputations": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "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 effect your sender rating.\n\nThis endpoint allows you to request the reputations for your subusers.", "operationId": "GET_subusers-reputations", "parameters": [ @@ -14962,12 +15160,6 @@ }, "type": "array" } - }, - "401": { - "description": "", - "schema": { - "type": "object" - } } }, "security": [ @@ -14984,9 +15176,7 @@ }, "/subusers/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "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.\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-stats", "parameters": [ @@ -15337,9 +15527,7 @@ }, "/subusers/stats/monthly": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\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\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-stats-monthly", "parameters": [ @@ -15474,9 +15662,7 @@ }, "/subusers/stats/sums": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**\n\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-stats-sums", "parameters": [ @@ -15569,20 +15755,10 @@ }, "/subusers/{subuser_name}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", "operationId": "DELETE_subusers-subuser_name", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -15590,6 +15766,7 @@ "204": { "description": "", "schema": { + "properties": {}, "type": "object" } }, @@ -15656,6 +15833,7 @@ "204": { "description": "", "schema": { + "properties": {}, "type": "object" } }, @@ -15737,6 +15915,7 @@ "in": "body", "name": "body", "schema": { + "description": "The IP addresses you would like to assign to the subuser.", "example": [ "127.0.0.1" ], @@ -15764,6 +15943,7 @@ "schema": { "properties": { "ips": { + "description": "The IP addresses that are assigned to the subuser.", "items": { "format": "ipv4", "type": "string" @@ -15796,20 +15976,10 @@ }, "/subusers/{subuser_name}/monitor": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", "operationId": "DELETE_subusers-subuser_name-monitor", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -15817,6 +15987,7 @@ "204": { "description": "", "schema": { + "properties": {}, "type": "object" } }, @@ -15856,9 +16027,7 @@ "summary": "Delete monitor settings" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", "operationId": "GET_subusers-subuser_name-monitor", "parameters": [], @@ -16080,9 +16249,7 @@ }, "/subusers/{subuser_name}/stats/monthly": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\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\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-subuser_name-stats-monthly", "parameters": [ @@ -16119,7 +16286,7 @@ "in": "query", "name": "limit", "required": false, - "type": "number" + "type": "integer" }, { "default": 0, @@ -16227,11 +16394,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -16245,9 +16408,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "GET_suppression-blocks", "parameters": [ @@ -16338,28 +16499,14 @@ }, "/suppression/blocks/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "DELETE_suppression-blocks-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "summary": "Delete a specific block", @@ -16368,9 +16515,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "GET_suppression-blocks-email", "parameters": [], @@ -16515,9 +16660,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your bounces.**\n\nBounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)", "operationId": "GET_suppression-bounces", "parameters": [ @@ -16525,19 +16668,13 @@ "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", "in": "query", "name": "start_time", - "type": "number" + "type": "integer" }, { "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", "in": "query", "name": "end_time", - "type": "number" - }, - { - "description": "", - "in": "header", - "name": "Allow", - "type": "string" + "type": "integer" } ], "produces": [ @@ -16614,9 +16751,7 @@ }, "/suppression/bounces/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an email address from your bounce list.**\n\nBounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)", "operationId": "DELETE_suppression-bounces-email", "parameters": [ @@ -16627,13 +16762,6 @@ "name": "email_address", "required": true, "type": "string" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [ @@ -16674,9 +16802,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific bounce for a given email address.**\n\nBounces are messages that are returned to the server that sent it.\n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)", "operationId": "GET_suppression-bounces-email", "parameters": [], @@ -16776,11 +16902,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -16791,9 +16913,7 @@ "summary": "Delete invalid emails" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all invalid email addresses.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "GET_suppression-invalid_emails", "parameters": [ @@ -16881,36 +17001,20 @@ }, "/suppression/invalid_emails/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a specific email address from the invalid email address list.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "DELETE_suppression-invalid_emails-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "summary": "Delete a specific invalid email" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific invalid email addresses.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "GET_suppression-invalid_emails-email", "parameters": [], @@ -16960,7 +17064,7 @@ }, "parameters": [ { - "description": "The invalid email address that you want to remove.", + "description": "The specific email address of the invalid email entry that you want to retrieve.", "in": "path", "name": "email", "required": true, @@ -16970,28 +17074,14 @@ }, "/suppression/spam_report/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "DELETE_suppression-spam_report-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -17002,9 +17092,7 @@ "summary": "Delete a specific spam report" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "GET_suppression-spam_report-email", "parameters": [], @@ -17059,7 +17147,7 @@ }, "parameters": [ { - "description": "The email address for the spam report that you want to delete.", + "description": "The email address of a specific spam report that you want to retrieve.", "in": "path", "name": "email", "required": true, @@ -17102,15 +17190,11 @@ "type": "object" } } - ], - "produces": [], - "responses": { - "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + ], + "produces": [], + "responses": { + "204": { + "description": "" } }, "security": [ @@ -17121,9 +17205,7 @@ "summary": "Delete spam reports" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all spam reports.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "GET_suppression-spam_reports", "parameters": [ @@ -17210,9 +17292,7 @@ }, "/suppression/unsubscribes": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "GET_suppression-unsubscribes", "parameters": [ @@ -17295,9 +17375,7 @@ }, "/templates": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all transactional templates.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).", "operationId": "GET_templates", "parameters": [], @@ -17385,27 +17463,14 @@ }, "/templates/{template_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", "operationId": "DELETE_templates-template_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -17416,9 +17481,7 @@ "summary": "Delete a template." }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", "operationId": "GET_templates-template_id", "parameters": [], @@ -17582,27 +17645,14 @@ }, "/templates/{template_id}/versions/{version_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete one of your transactional template versions.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "DELETE_templates-template_id-versions-version_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "null" - } + "description": "" } }, "security": [ @@ -17613,9 +17663,7 @@ "summary": "Delete a transactional template version." }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific version of a template.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "GET_templates-template_id-versions-version_id", "parameters": [], @@ -17788,20 +17836,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to activate a version of one of your templates.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "POST_templates-template_id-versions-version_id-activate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -17852,9 +17890,7 @@ }, "/tracking_settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings", "parameters": [ @@ -17932,9 +17968,7 @@ }, "/tracking_settings/click": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current click tracking setting.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-click", "parameters": [], @@ -18042,9 +18076,7 @@ }, "/tracking_settings/google_analytics": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current setting for Google Analytics.**\n\nFor more information about using Google Analytics, please refer to [Google\u2019s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on [\"Best Practices for Campaign Building\"](https://support.google.com/analytics/answer/1037445).\n\nWe default the settings to Google\u2019s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html).\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-google_analytics", "parameters": [], @@ -18131,9 +18163,7 @@ }, "/tracking_settings/open": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current settings for open tracking.**\n\nOpen Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid\u2019s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-open", "parameters": [], @@ -18229,9 +18259,7 @@ }, "/tracking_settings/subscription": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-subscription", "parameters": [], @@ -18318,9 +18346,7 @@ }, "/user/account": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your user account details.**\n\nYour user's account information includes the user's account type and reputation.\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-account", "parameters": [], @@ -18374,9 +18400,7 @@ }, "/user/credits": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the current credit balance for your account.**\n\nYour monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html).", "operationId": "GET_user-credits", "parameters": [], @@ -18455,9 +18479,7 @@ }, "/user/email": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the email address currently on file for your account.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-email", "parameters": [], @@ -18590,11 +18612,7 @@ "produces": [], "responses": { "200": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -18610,9 +18628,7 @@ }, "/user/profile": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-profile", "parameters": [], @@ -18699,12 +18715,6 @@ "title": "GET User Profile response", "type": "object" } - }, - "401": { - "description": "", - "schema": { - "type": "object" - } } }, "security": [ @@ -18736,12 +18746,6 @@ "last_name": "User" } } - }, - { - "description": "You can enter a subuser name as the value for this header, in order to update the subuser's profile.", - "in": "header", - "name": "on-behalf-of", - "type": "string" } ], "produces": [ @@ -18799,9 +18803,7 @@ }, "/user/scheduled_sends": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all cancel/paused scheduled send information.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "operationId": "GET_user-scheduled_sends", "parameters": [], @@ -18956,20 +18958,10 @@ }, "/user/scheduled_sends/{batch_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete the cancellation/pause of a scheduled send.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "operationId": "DELETE_user-scheduled_sends-batch_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -19021,9 +19013,7 @@ "summary": "Delete a cancellation or pause of a scheduled send" }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "operationId": "GET_user-scheduled_sends-batch_id", "parameters": [], @@ -19185,9 +19175,7 @@ }, "/user/settings/enforced_tls": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Enforced TLS settings.**\n\nThe Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS.\n\n**Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with \u201cTLS required but not supported\u201d as the description.", "operationId": "GET_user-settings-enforced_tls", "parameters": [], @@ -19300,9 +19288,7 @@ }, "/user/username": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current account username.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-username", "parameters": [], @@ -19410,9 +19396,7 @@ }, "/user/webhooks/event/settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid\u2019s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", "operationId": "GET_user-webhooks-event-settings", "parameters": [], @@ -19553,9 +19537,169 @@ "produces": [], "responses": { "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Test Event Notification Settings ", + "tags": [ + "Webhooks" + ] + } + }, + "/user/webhooks/parse/settings": { + "get": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to retrieve all of your current inbound parse settings.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "GET_user-webhooks-parse-settings", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "result": [ + { + "hostname": "mail.mydomain.com", + "send_raw": true, + "spam_check": true, + "url": "http://mydomain.com/parse" + } + ] + } + }, + "schema": { + "properties": { + "result": { + "description": "The list of your current inbound parse settings.", + "items": { + "$ref": "#/definitions/parse-setting" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve all parse settings", + "tags": [ + "Settings - Inbound Parse" + ] + }, + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to create a new inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "POST_user-webhooks-parse-settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/parse-setting", + "example": { + "hostname": "myhostname.com", + "send_raw": false, + "spam_check": true, + "url": "http://email.myhosthame.com" + } + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", + "examples": { + "application/json": { + "hostname": "myhostname.com", + "send_raw": true, + "spam_check": false, + "url": "http://email.myhostname.com" + } + }, + "schema": { + "$ref": "#/definitions/parse-setting" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Create a parse setting", + "tags": [ + "Settings - Inbound Parse" + ] + } + }, + "/user/webhooks/parse/settings/{hostname}": { + "delete": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to delete a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "DELETE_user-webhooks-parse-settings-hostname", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Delete a parse setting", + "tags": [ + "Settings - Inbound Parse" + ] + }, + "get": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to retrieve a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "GET_user-webhooks-parse-settings-hostname", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { "description": "", + "examples": { + "application/json": { + "hostname": "mail.mydomain.com", + "send_raw": true, + "spam_check": true, + "url": "http://mydomain.com/parse" + } + }, "schema": { - "type": "object" + "$ref": "#/definitions/parse-setting" } } }, @@ -19564,20 +19708,51 @@ "Authorization": [] } ], - "summary": "Test Event Notification Settings ", + "summary": "Retrieve a specific parse setting", "tags": [ - "Webhooks" + "Settings - Inbound Parse" ] - } + }, + "parameters": [ + { + "description": "The hostname associated with the inbound parse setting that you want to delete.", + "in": "path", + "name": "hostname", + "required": true, + "type": "string" + } + ] }, - "/user/webhooks/parse/settings": { - "get": { + "/user/webhooks/parse/settings/{hostname}/": { + "parameters": [ + { + "description": "The hostname associated with the specific inbound parse setting that you want to update.", + "in": "path", + "name": "hostname", + "required": true, + "type": "string" + } + ], + "patch": { "consumes": [ "application/json" ], - "description": "**This endpoint allows you to retrieve your current inbound parse webhook settings.**\n\nSendGrid can parse the attachments and contents of incoming emails. The Parse API will POST the parsed email to a URL that you specify. For more information, see our Inbound [Parse Webhook documentation](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", - "operationId": "GET_user-webhooks-parse-settings", - "parameters": [], + "description": "**This endpoint allows you to update a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "PATCH_user-webhooks-parse-settings-hostname", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/parse-setting", + "example": { + "send_raw": true, + "spam_check": false, + "url": "http://newdomain.com/parse" + } + } + } + ], "produces": [ "application/json" ], @@ -19586,54 +19761,14 @@ "description": "", "examples": { "application/json": { - "result": [ - { - "hostname": "example.com", - "send_raw": false, - "spam_check": false, - "url": "http://example.com/example" - } - ] + "hostname": "mail.mydomain.com", + "send_raw": true, + "spam_check": true, + "url": "http://mydomain.com/parse" } }, "schema": { - "properties": { - "result": { - "description": "The array containing the parse webhook settings.", - "items": { - "properties": { - "hostname": { - "description": "The hostname of the URL where you would like your parsed emails to be posted.", - "type": "string" - }, - "send_raw": { - "description": "Indicates if the raw content that was parsed will be posted.", - "type": "boolean" - }, - "spam_check": { - "description": "Indicates if the parsed content will be checked for spam.", - "type": "boolean" - }, - "url": { - "description": "The URL where you want your parsed emails to be posted.", - "type": "string" - } - }, - "required": [ - "hostname", - "url", - "spam_check", - "send_raw" - ], - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "result" - ], - "type": "object" + "$ref": "#/definitions/parse-setting" } } }, @@ -19642,18 +19777,12 @@ "Authorization": [] } ], - "summary": "Retrieve Parse Webhook settings", - "tags": [ - "Webhooks" - ] - }, - "parameters": [] + "summary": "Update a parse setting" + } }, "/user/webhooks/parse/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the statistics for your Parse Webhook useage.**\n\nSendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments.\n\nThere are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries).", "operationId": "GET_user-webhooks-parse-stats", "parameters": [ @@ -20072,9 +20201,7 @@ }, "/whitelabel/domains": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all domain whitelabels you have created.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", "operationId": "GET_whitelabel-domains", "parameters": [ @@ -20483,9 +20610,7 @@ }, "/whitelabel/domains/default": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the default whitelabel for a domain.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| domain | string |The domain to find a default domain whitelabel for. |", "operationId": "GET_whitelabel-domains-default", "parameters": [], @@ -20514,27 +20639,14 @@ }, "/whitelabel/domains/subuser": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to disassociate a specific whitelabel from a subuser.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n| username | string | required | Username for the subuser to find associated whitelabels for. |", "operationId": "DELETE_whitelabel-domains-subuser", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -20548,9 +20660,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| username | string | Username of the subuser to find associated whitelabels for. |", "operationId": "GET_whitelabel-domains-subuser", "parameters": [], @@ -20620,27 +20730,14 @@ }, "/whitelabel/domains/{domain_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a domain whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", "operationId": "DELETE_whitelabel-domains-domain_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -20651,9 +20748,7 @@ "summary": "Delete a domain whitelabel." }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific domain whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", "operationId": "GET_whitelabel-domains-domain_id", "parameters": [], @@ -20675,7 +20770,15 @@ ], "summary": "Retrieve a domain whitelabel." }, - "parameters": [], + "parameters": [ + { + "description": "The id of the domain whitelabel.", + "in": "path", + "name": "domain_id", + "required": true, + "type": "number" + } + ], "patch": { "consumes": [ "application/json" @@ -20934,20 +21037,10 @@ }, "/whitelabel/domains/{id}/ips/{ip}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a domain's IP address from that domain's whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain whitelabel to delete the IP from. |\n| ip | string | IP to remove from the domain whitelabel. |", "operationId": "DELETE_whitelabel-domains-id-ips-ip", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -21035,20 +21128,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer |ID of the domain whitelabel to validate. |", "operationId": "POST_whitelabel-domains-id-validate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -21152,12 +21235,6 @@ "type": "object" } }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object" - } - }, "500": { "description": "", "examples": { @@ -21204,9 +21281,7 @@ }, "/whitelabel/ips": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.**\n\nYou may include a search key by using the \"ip\" parameter. This enables you to perform a prefix search for a given IP segment (e.g. \"192.\").\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "GET_whitelabel-ips", "parameters": [ @@ -21389,20 +21464,10 @@ }, "/whitelabel/ips/{id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "DELETE_whitelabel-ips-id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -21455,9 +21520,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "GET_whitelabel-ips-id", "parameters": [], @@ -21543,7 +21606,7 @@ }, "parameters": [ { - "description": "The id of the IP whitelabel that you would like to retrieve.", + "description": "The id of the IP whitelabel that you want to delete.", "in": "path", "name": "id", "required": true, @@ -21561,20 +21624,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "POST_whitelabel-ips-id-validate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -21732,9 +21785,7 @@ }, "/whitelabel/links": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all link whitelabels.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links", "parameters": [ @@ -21928,9 +21979,7 @@ }, "/whitelabel/links/default": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the default link whitelabel.**\n\nDefault link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order:\n\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links-default", "parameters": [ @@ -21992,9 +22041,7 @@ }, "/whitelabel/links/subuser": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to disassociate a link whitelabel from a subuser.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "DELETE_whitelabel-links-subuser", "parameters": [ @@ -22004,22 +22051,12 @@ "name": "username", "required": true, "type": "string" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -22033,9 +22070,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the associated link whitelabel for a subuser.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links-subuser", "parameters": [ @@ -22098,27 +22133,14 @@ }, "/whitelabel/links/{id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "DELETE_whitelabel-links-id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -22132,9 +22154,7 @@ ] }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links-id", "parameters": [], @@ -22187,7 +22207,7 @@ }, "parameters": [ { - "description": "The id of the link whitelabel you want to retrieve.", + "description": "The id of the link whitelabel that you want to delete.", "in": "path", "name": "id", "required": true, @@ -22281,20 +22301,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "POST_whitelabel-links-id-validate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -22399,12 +22409,6 @@ "type": "object" } }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object" - } - }, "500": { "description": "", "examples": { diff --git a/oai.yaml b/oai.yaml index 71af1dc..d2922c3 100644 --- a/oai.yaml +++ b/oai.yaml @@ -13,90 +13,114 @@ consumes: produces: - application/json paths: - '/asm/groups/{group_id}': - parameters: - - name: group_id - in: path - description: The id of the suppression group you want to delete. - required: true - type: integer - delete: - summary: Delete a suppression group. + /subusers/stats/sums: + parameters: [] + get: + tags: + - Stats - Subuser Stats + summary: ' Retrieve the totals for each email statistic metric for all subusers.' description: |- - **This endpoint allows you to delete a suppression group.** - - You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. + **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** - Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - Each user can create up to 25 different suppression groups. - operationId: DELETE_asm-groups-group_id - consumes: - - application/json + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: GET_subusers-stats-sums + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - type: 'null' + - name: sort_by_direction + in: query + description: 'The direction you want to sort. ' + required: false + type: string + default: desc + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + 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 + type: string + - name: limit + in: query + description: Limits the number of results returned per page. + required: false + type: integer + default: 5 + - name: offset + in: query + description: The point in the list to begin retrieving results from. + required: false + 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 + type: string + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + default: delivered responses: - '204': + '200': description: '' schema: - type: object + $ref: '#/definitions/category_stats' + examples: + application/json: + date: '2015-10-11' + stats: [] security: - Authorization: [] - get: - summary: Get information on a single suppression group. + '/whitelabel/links/{id}': + parameters: + - name: id + in: path + description: The id of the link whitelabel that you want to delete. + required: true + type: integer + delete: + tags: + - Whitelabel - Links + summary: Delete a Link Whitelabel description: |- - **This endpoint allows you to retrieve a single suppression group.** - - Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + **This endpoint allows you to delete a link whitelabel.** - The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - Each user can create up to 25 different suppression groups. - operationId: GET_asm-groups-group_id - consumes: - - application/json - produces: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: DELETE_whitelabel-links-id + consumes: [] + produces: [] parameters: [] responses: - '200': + '204': description: '' - schema: - allOf: - - $ref: '#/definitions/suppression_group' - - properties: - unsubscribes: - type: integer - description: The unsubscribes associated with this group. - type: object - examples: - application/json: - id: 100 - name: Newsletters - description: Our monthly newsletter. - last_email_sent_at: null - is_default: true - unsubscribes: 400 security: - Authorization: [] patch: - summary: Update a suppression group. + tags: + - Whitelabel - Links + summary: Update a Link Whitelabel description: |- - **This endpoint allows you to update or change a suppression group.** - - Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + **This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.** - The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - Each user can create up to 25 different suppression groups. - operationId: PATCH_asm-groups-group_id + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: PATCH_whitelabel-links-id consumes: - application/json produces: @@ -107,105 +131,54 @@ paths: schema: type: object properties: - id: - type: number - description: The id of the suppression group. - name: - type: string - description: The name of the suppression group. Each group created by a user must have a unique name. - maxLength: 30 - description: - type: string - description: The description of the suppression group. - maxLength: 100 - is_default: + default: type: boolean - description: Indicates if the suppression group is set as the default group. - required: - - name + description: 'Indicates if the link whitelabel is set as the default, or fallback, whitelabel.' + enum: + - true + - false example: - id: 103 - name: Item Suggestions - description: Suggestions for items our users might like. - responses: - '201': - description: '' - schema: - $ref: '#/definitions/suppression_group' - examples: - application/json: - id: 103 - name: Item Suggestions - description: Suggestions for items our users might like. - '/suppression/bounces/{email}': - parameters: - - name: email - in: path - required: true - type: string - delete: - tags: - - Bounces API - summary: Delete a bounce - description: |- - **This endpoint allows you to remove an email address from your bounce list.** - - Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. - - For more information see: - - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) - operationId: DELETE_suppression-bounces-email - consumes: - - application/json - produces: - - application/json - parameters: - - name: email_address - in: query - description: The email address you would like to remove from the bounce list. - required: true - type: string - format: email - - name: body - in: body - schema: - type: 'null' + default: true responses: - '204': - description: '' - schema: - type: object - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/link_whitelabel' examples: application/json: - errors: - - field: null - message: authorization required + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: true + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] get: tags: - - Bounces API - summary: Retrieve a Bounce + - Whitelabel - Links + summary: Retrieve a Link Whitelabel description: |- - **This endpoint allows you to retrieve a specific bounce for a given email address.** - - Bounces are messages that are returned to the server that sent it. + **This endpoint allows you to retrieve a specific link whitelabel.** - For more information see: + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) - operationId: GET_suppression-bounces-email - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: GET_whitelabel-links-id + consumes: [] produces: - application/json parameters: [] @@ -213,122 +186,470 @@ paths: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - email: - type: string - reason: - type: string - status: - type: string + $ref: '#/definitions/link_whitelabel' examples: application/json: - - created: 1443651125 - email: bounce1@test.com - reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' - status: 5.1.1 + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - /subusers/reputations: + /categories/stats/sums: parameters: [] get: tags: - - Subusers API - summary: Retrieve Subuser Reputations + - Stats - Category Stats + summary: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' description: |- - 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 effect your sender rating. + **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** - This endpoint allows you to request the reputations for your subusers. - operationId: GET_subusers-reputations - consumes: - - application/json + If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + + Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). + operationId: GET_categories-stats-sums + consumes: [] produces: - application/json parameters: - - name: usernames + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + default: delivered + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + default: desc + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + 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 + type: string + - name: limit + in: query + description: Limits the number of results returned. + required: false + type: integer + default: 5 + - name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + default: 0 + - name: aggregated_by in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false type: string + enum: + - day + - week + - month responses: '200': description: '' 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.f - required: - - reputation - - username + type: object + properties: + '': + $ref: '#/definitions/category_stats' examples: application/json: - - username: example_subuser - reputation: 99 - - username: example_subuser2 - reputation: 95.2 - '401': - description: '' - schema: - type: object + date: '2015-01-01' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 20 + deferred: 0 + delivered: 20 + invalid_emails: 0 + opens: 20 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 20 + unique_opens: 20 + unsubscribe_drops: 0 + unsubscribes: 20 + name: cat1 + type: category + - metrics: + blocks: 1 + bounce_drops: 0 + bounces: 0 + clicks: 19 + deferred: 0 + delivered: 19 + invalid_emails: 0 + opens: 19 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 19 + unique_opens: 19 + unsubscribe_drops: 0 + unsubscribes: 19 + name: cat2 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 5 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 5 + name: cat3 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 6 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 6 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 6 + name: cat4 + type: category + - metrics: + blocks: 10 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: cat5 + type: category security: - Authorization: [] - /user/scheduled_sends: + /stats: parameters: [] get: - summary: Retrieve all scheduled sends + tags: + - Stats - Global Stats + summary: Retrieve global email statistics description: |- - **This endpoint allows you to retrieve all cancel/paused scheduled send information.** + **This endpoint allows you to retrieve all of your global email statistics between a given date range.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: GET_user-scheduled_sends - consumes: - - application/json + Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. + operationId: GET_stats + consumes: [] produces: - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/user_scheduled_send_status' - examples: - application/json: - - batch_id: YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg - status: cancel - - batch_id: UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2 - status: cancel - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: + parameters: + - name: limit + in: query + description: The number of results to return. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + 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 + type: string + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + date: + type: string + description: The date the stats were gathered. + stats: + type: array + description: The individual email activity stats. + 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 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. + required: + - date + - stats + examples: + application/json: + - date: '2015-11-03' + 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 + - date: '2015-11-04' + 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 + - date: '2015-11-05' + 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 + - date: '2015-11-06' + 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 + - date: '2015-11-07' + 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 + - date: '2015-11-08' + 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 + - date: '2015-11-09' + 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 + security: - Authorization: [] + '/asm/groups/{group_id}/suppressions': + parameters: + - name: group_id + in: path + description: The id of the unsubscribe group that you are adding suppressions to. + required: true + type: string post: - summary: Cancel or pause a scheduled send + summary: Add suppressions to a suppression group description: |- - **This endpoint allows you to cancel or pause an email that has been scheduled to be sent.** + **This endpoint allows you to add email addresses to an unsubscribe group.** - If the maximum number of cancellations/pauses are added, HTTP 400 will - be returned. + If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: POST_user-scheduled_sends + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: POST_asm-groups-group_id-suppressions consumes: - application/json produces: @@ -337,200 +658,155 @@ paths: - name: body in: body schema: - title: Cancel or pause a scheduled send request type: object properties: - batch_id: - type: string - description: The batch ID is the identifier that your scheduled mail sends share. - pattern: '^[a-zA-Z0-9]' - status: - type: string - default: pause - description: 'The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}' - enum: - - pause - - cancel + recipient_emails: + type: array + description: The email address that you want to add to the unsubscribe group. + items: + type: string required: - - batch_id - - status + - recipient_emails example: - batch_id: YOUR_BATCH_ID - status: pause + recipient_emails: + - test1@example.com + - test2@example.com responses: '201': - description: '' - schema: - $ref: '#/definitions/user_scheduled_send_status' - '400': - description: |- - "" : "max limit reached" - "batch_id" : "invalid batch id" - "batch_id" : "a status for this batch id exists, try PATCH to update the status" - schema: - type: object - examples: - application/json: - errors: - - field: null - message: max limit reached - - field: batch_id - message: invalid batch id - - field: batch_id - message: 'a status for this batch id exists, try PATCH to update the status' - '401': description: '' schema: type: object + properties: + recipient_emails: + type: array + description: The email address that were added to the suppressions list. + items: + type: string + required: + - recipient_emails examples: application/json: - errors: - - field: null - message: authorization required + recipient_emails: + - test1@example.com + - test2@example.com security: - Authorization: [] - /mail_settings/bounce_purge: - parameters: [] - patch: - summary: Update bounce purge mail settings + get: + summary: Retrieve all suppressions for a suppression group description: |- - **This endpoint allows you to update your current bounce purge settings.** - - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-bounce_purge - consumes: - - application/json + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: GET_asm-groups-group_id-suppressions + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_bounce_purge' - example: - enabled: true - hard_bounces: 5 - soft_bounces: 5 + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' + type: array + description: The list of email addresses belonging to the given suppression group. + items: + type: string examples: application/json: - enabled: false - hard_bounces: null - soft_bounces: null + - example@example.com + - example2@example.com security: - Authorization: [] - get: - summary: Retrieve bounce purge mail settings + '/asm/groups/{group_id}': + parameters: + - name: group_id + in: path + description: The id of the suppression group you want to delete. + required: true + type: integer + delete: + summary: Delete a suppression group. description: |- - **This endpoint allows you to retrieve your current bounce purge settings.** + **This endpoint allows you to delete a suppression group.** - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-bounce_purge - consumes: - - application/json + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: DELETE_asm-groups-group_id + consumes: [] produces: - application/json parameters: [] responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' - examples: - application/json: - enabled: false - soft_bounces: 1234 - hard_bounces: null + type: object security: - Authorization: [] - '/whitelabel/ips/{id}': - parameters: - - name: id - in: path - description: The id of the IP whitelabel that you would like to retrieve. - required: true - type: string get: - tags: - - Whitelabel - IPs - summary: Retrieve an IP whitelabel + summary: Get information on a single suppression group. description: |- - **This endpoint allows you to retrieve an IP whitelabel.** + **This endpoint allows you to retrieve a single suppression group.** - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: GET_whitelabel-ips-id - consumes: - - application/json + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: GET_asm-groups-group_id + consumes: [] produces: - application/json parameters: [] responses: '200': - description: '' - schema: - $ref: '#/definitions/ip_whitelabel' - examples: - application/json: - id: 123 - ip: 192.168.1.1 - rdns: o1.email.example.com - users: - - username: john@example.com - user_id: 7 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.1 - '404': description: '' schema: type: object properties: - errors: - type: array - description: The errors preventing the retrieval of the IP whitelabel. - items: - type: object - properties: - message: - type: string - description: A message explaining why the IP whitelabel could not be found. - required: - - message - required: - - errors + description: + type: string + description: The description of the suppression group. + id: + type: integer + description: The ID of the suppression group. + is_default: + type: boolean + description: Indicates if this is the default suppression group. + last_email_sent_at: + type: 'null' + description: A unix timestamp indicating the last time this group was assigned to an email. + name: + type: string + description: The name of the suppression group. + unsubscribes: + type: integer + description: 'The number of unsubscribes, or suppressions, in this group.' examples: application/json: - errors: - - message: Whitelabel ip not found. + description: Our monthly newsletter. + id: 100 + is_default: true + last_email_sent_at: null + name: Newsletters + unsubscribes: 400 security: - Authorization: [] - delete: - tags: - - Whitelabel - IPs - summary: Delete an IP whitelabel + patch: + summary: Update a suppression group. description: |- - **This endpoint allows you to delete an IP whitelabel.** + **This endpoint allows you to update or change a suppression group.** - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: DELETE_whitelabel-ips-id + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: PATCH_asm-groups-group_id consumes: - application/json produces: @@ -538,312 +814,222 @@ paths: parameters: - name: body in: body - schema: - type: 'null' - responses: - '204': - description: '' schema: type: object - '404': + properties: + id: + type: integer + description: The id of the suppression group. + name: + type: string + description: The name of the suppression group. Each group created by a user must have a unique name. + maxLength: 30 + description: + type: string + description: The description of the suppression group. + maxLength: 100 + is_default: + type: boolean + description: Indicates if the suppression group is set as the default group. + required: + - name + example: + id: 103 + name: Item Suggestions + description: Suggestions for items our users might like. + responses: + '201': description: '' schema: - type: object - properties: - errors: - type: array - description: The errors preventing the IP whitelabel from being deleted. - items: - type: object - properties: - message: - type: string - description: A message explaining why the IP whitelabel could not be deleted. + $ref: '#/definitions/suppression_group' examples: application/json: - errors: - - message: Whitelabel ip not found. - security: - - Authorization: [] - /contactdb/recipients: + id: 103 + name: Item Suggestions + description: Suggestions for items our users might like. + /mail_settings/bcc: parameters: [] - post: - tags: - - Contacts API - Recipients - summary: Add recipients + get: + summary: Retrieve all BCC mail settings description: |- - **This endpoint allows you to add a Marketing Campaigns recipient.** + **This endpoint allows you to retrieve your current BCC mail settings.** - It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: POST_contactdb-recipients - consumes: - - application/json + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-bcc + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: array - items: - type: object - properties: - email: - type: string - description: The email address of the recipient. - format: email - first_name: - type: string - description: The first name of the recipient. - last_name: - type: string - description: The last name of the recipient. - required: - - email - example: - - email: example@example.com - first_name: '' - last_name: User - age: 25 - - email: example2@example.com - first_name: Example - last_name: User - age: 25 + parameters: [] responses: - '201': - description: '' - schema: - $ref: '#/definitions/contactdb_recipient_response' - examples: - application/json: - error_count: 1 - error_indices: - - 2 - new_count: 2 - persisted_recipients: - - YUBh - - bWlsbGVyQG1pbGxlci50ZXN0 - updated_count: 0 - errors: - - message: Invalid email. - error_indices: - - 2 - '400': - description: '"" : "Returned if request body is not valid json"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: Request body is not valid json - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_bcc' examples: application/json: - errors: - - field: null - message: authorization required + email: example@example.com + enabled: false security: - Authorization: [] - get: - tags: - - Contacts API - Recipients - summary: Retrieve recipients + patch: + summary: Update BCC mail settings description: |- - **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** + **This endpoint allows you to update your current BCC mail settings.** - Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of - the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-recipients + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-bcc consumes: - application/json produces: - application/json parameters: - - name: page - in: query - description: Page index of first recipients to return (must be a positive integer) - type: integer - - name: page_size - in: query - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - type: integer + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_patch' + example: + enabled: false + email: email@example.com responses: '200': description: '' schema: - title: List Recipients response - type: object - properties: - recipients: - type: array - items: - type: object - required: - - recipients - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" - schema: - type: object - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_patch' examples: application/json: - errors: - - field: null - message: authorization required + email: example@example.com + enabled: false security: - Authorization: [] - patch: + /suppression/blocks: + parameters: [] + get: tags: - - Contacts API - Recipients - summary: Update Recipient + - Blocks API + summary: Retrieve all blocks description: |- - **This endpoint allows you to update one or more recipients.** - - The body of an API call to this endpoint must include an array of one or more recipient objects. + **This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** - It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: PATCH_contactdb-recipients - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: GET_suppression-blocks + consumes: [] produces: - application/json parameters: - - name: body - in: body + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when a blocked email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when a blocked email was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: The point in the list to begin displaying results. + type: integer + responses: + '200': + description: '' schema: type: array items: type: object properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the blocks list. email: type: string - format: email - last_name: + description: The email address that was added to the block list. + reason: type: string - description: The last name of the recipient. This is one of the default custom fields. - first_name: + description: An explanation for the reason of the block. + status: type: string - description: The first name of the recipient. This is one of the default custom fields. + description: The status of the block. required: + - created - email - example: - - email: jones@example.com - last_name: Jones - first_name: Guy - responses: - '201': - description: '' - schema: - $ref: '#/definitions/contactdb_recipient_response' - '400': - description: '"" : "Returned if request body is not valid json"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: Request body is not valid json - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + - reason + - status examples: application/json: - errors: - - field: null - message: authorization required + - created: 1443651154 + email: user1@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 security: - Authorization: [] delete: tags: - - Contacts API - Recipients - summary: Delete Recipient + - Blocks API + summary: Delete blocks description: |- - **This endpoint allows you to deletes one or more recipients.** + **This endpoint allows you to delete all email addresses on your blocks list.** - The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. + There are two options for deleting blocked emails: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: DELETE_contactdb-recipients + 1. You can delete all blocked emails by setting `delete_all` to true in the request body. + 2. You can delete some blocked emails by specifying the email addresses in an array in the request body. + + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: DELETE_suppression-blocks consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: - type: array - items: - type: string + type: object + properties: + delete_all: + type: boolean + description: Indicates if you want to delete all blocked email addresses. + emails: + type: array + description: The specific blocked email addresses that you want to delete. + items: + type: string example: - - recipient_id1 - - recipient_id2 + delete_all: false + emails: + - example1@example.com + - example2@example.com responses: - '200': - description: '' - schema: - type: object - '400': - description: |- - "" : "Returned if no recipients are deleted" - "" : "Returned if all of the provided recipient ids are invalid" - "" : "Returned if request body is not valid json" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: No recipient ids provided - '401': + '204': description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required security: - Authorization: [] - /whitelabel/domains/default: + /user/webhooks/event/settings: parameters: [] get: tags: - - Whitelabel - Domains - summary: Get the default domain whitelabel. + - Webhooks + summary: Retrieve Event Webhook settings description: |- - **This endpoint allows you to retrieve the default whitelabel for a domain.** + **This endpoint allows you to retrieve your current event webhook settings.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + If an event type is marked as `true`, then the event webhook will include information about that event. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | domain | string |The domain to find a default domain whitelabel for. | - operationId: GET_whitelabel-domains-default - consumes: - - application/json + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + operationId: GET_user-webhooks-event-settings + consumes: [] produces: - application/json parameters: [] @@ -851,64 +1037,37 @@ paths: '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' - security: - - Authorization: [] - '/templates/{template_id}/versions/{version_id}': - parameters: - - name: template_id - in: path - required: true - type: string - - name: version_id - in: path - required: true - type: string - delete: - summary: Delete a transactional template version. - description: |- - **This endpoint allows you to delete one of your transactional template versions.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - operationId: DELETE_templates-template_id-versions-version_id - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: 'null' + $ref: '#/definitions/event_webhook_settings' + examples: + application/json: + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true security: - Authorization: [] patch: - summary: Edit a transactional template version. + tags: + - Webhooks + summary: Update Event Notification Settings description: |- - **This endpoint allows you to edit a version of one of your transactional templates.** + **This endpoint allows you to update your current event webhook settings.** - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + If an event type is marked as `true`, then the event webhook will include information about that event. - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - operationId: PATCH_templates-template_id-versions-version_id + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + operationId: PATCH_user-webhooks-event-settings consumes: - application/json produces: @@ -917,257 +1076,212 @@ paths: - name: body in: body schema: - type: object - properties: - active: - type: integer - description: Indicates if the template version is active. - name: - type: string - description: The name of the template version. - html_content: - type: string - description: The HTML content of the template version. - plain_content: - type: string - description: The text/plain content of the template version. - subject: - type: string - description: The subject of the template version. + $ref: '#/definitions/event_webhook_settings' example: - active: 1 - name: updated_example_name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true responses: '200': description: '' schema: - type: object - properties: - id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the template version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_template_version' - required: - - id - - updated_at + $ref: '#/definitions/event_webhook_settings' examples: application/json: - id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f - template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d - active: 1 - name: version 1 name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> - updated_at: '2014-03-19 18:56:33' + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true security: - Authorization: [] + /subusers/reputations: + parameters: [] get: - summary: Retrieve a specific transactional template version. + tags: + - Subusers API + summary: Retrieve Subuser Reputations description: |- - **This endpoint allows you to retrieve a specific version of a template.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + 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 effect your sender rating. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - operationId: GET_templates-template_id-versions-version_id - consumes: - - application/json + This endpoint allows you to request the reputations for your subusers. + operationId: GET_subusers-reputations + consumes: [] produces: - application/json - parameters: [] + parameters: + - name: usernames + in: query + type: string responses: '200': description: '' schema: - type: object - properties: - id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the template version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_template_version' - required: - - id - - updated_at - examples: - application/json: - id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f - template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d - active: 1 - name: version 1 name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> - updated_at: '2014-03-19 18:56:33' + 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.f + required: + - reputation + - username + examples: + application/json: + - username: example_subuser + reputation: 99 + - username: example_subuser2 + reputation: 95.2 security: - Authorization: [] - '/whitelabel/links/{id}': + '/suppression/bounces/{email}': parameters: - - name: id + - name: email in: path - description: The id of the link whitelabel you want to retrieve. required: true - type: integer - get: + type: string + delete: tags: - - Whitelabel - Links - summary: Retrieve a Link Whitelabel + - Bounces API + summary: Delete a bounce description: |- - **This endpoint allows you to retrieve a specific link whitelabel.** + **This endpoint allows you to remove an email address from your bounce list.** - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: GET_whitelabel-links-id - consumes: - - application/json + For more information see: + + * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information + * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) + * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) + operationId: DELETE_suppression-bounces-email + consumes: [] produces: - application/json - parameters: [] + parameters: + - name: email_address + in: query + description: The email address you would like to remove from the bounce list. + required: true + type: string + format: email responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/link_whitelabel' + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net + errors: + - field: null + message: authorization required security: - Authorization: [] - delete: + get: tags: - - Whitelabel - Links - summary: Delete a Link Whitelabel + - Bounces API + summary: Retrieve a Bounce description: |- - **This endpoint allows you to delete a link whitelabel.** + **This endpoint allows you to retrieve a specific bounce for a given email address.** - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + Bounces are messages that are returned to the server that sent it. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: DELETE_whitelabel-links-id - consumes: + For more information see: + + * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information + * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) + * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) + operationId: GET_suppression-bounces-email + consumes: [] + produces: - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: - '204': + '200': description: '' schema: - type: object + type: array + items: + type: object + properties: + created: + type: integer + email: + type: string + reason: + type: string + status: + type: string + examples: + application/json: + - created: 1443651125 + email: bounce1@test.com + reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' + status: 5.1.1 security: - Authorization: [] - patch: - tags: - - Whitelabel - Links - summary: Update a Link Whitelabel + /mail_settings/address_whitelist: + parameters: [] + get: + summary: Retrieve address whitelist mail settings description: |- - **This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.** + **This endpoint allows you to retrieve your current email address whitelist settings.** - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: PATCH_whitelabel-links-id - consumes: - - application/json + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-address_whitelist + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - default: - type: boolean - description: 'Indicates if the link whitelabel is set as the default, or fallback, whitelabel.' - enum: - - true - - false - example: - default: true + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/link_whitelabel' + $ref: '#/definitions/mail_settings_address_whitelabel' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: true - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net + enabled: false + list: + - example.com security: - Authorization: [] - '/subusers/{subuser_name}': - parameters: - - name: subuser_name - in: path - required: true - type: string - delete: - summary: Delete a subuser + patch: + summary: Update address whitelist mail settings description: |- - This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. + **This endpoint allows you to update your current email address whitelist settings.** - For more information about Subusers: + The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: DELETE_subusers-subuser_name + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-address_whitelist consumes: - application/json produces: @@ -1175,303 +1289,470 @@ paths: parameters: - name: body in: body - schema: - type: 'null' - responses: - '204': - description: '' schema: type: object - '401': + properties: + enabled: + type: boolean + description: Indicates if your email address whitelist is enabled. + list: + type: array + description: 'Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.' + items: + type: string + example: + enabled: true + list: + - email1@example.com + - example.com + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_address_whitelabel' examples: application/json: - errors: - - field: null - message: authorization required + enabled: true + list: + - email1@example.com security: - Authorization: [] - patch: - summary: Enable/disable a subuser + /alerts: + parameters: [] + post: + tags: + - Alerts + summary: Create a new Alert description: |- - This endpoint allows you to enable or disable a subuser. + **This endpoint allows you to create a new alert.** - For more information about Subusers: + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: PATCH_subusers-subuser_name + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: POST_alerts consumes: - application/json produces: - application/json + - text/plain parameters: - name: body in: body schema: type: object properties: - disabled: - type: boolean - description: 'Whether or not this subuser is disabled. True means disabled, False means enabled.' + type: + type: string + description: |- + The type of alert you want to create. Can be either usage_alert or stats_notification. + Example: usage_alert + email_to: + type: string + description: |- + The email address the alert will be sent to. + Example: test@example.com + frequency: + type: string + description: |- + Required for stats_notification. How frequently the alert will be sent. + Example: daily + percentage: + type: integer + description: |- + Required for usage_alert. When this usage threshold is reached, the alert will be sent. + Example: 90 + required: + - type + - email_to example: - disabled: false + type: stats_notification + email_to: eric.schallock@sendgrid.com + frequency: daily + - name: Authorization + in: header + description: '' + type: string responses: - '204': + '201': description: '' schema: type: object - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: invalid username - - message: no fields provided - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '500': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' examples: - application/json: - errors: - - message: unable to enable user + text/plain: + id: 304575 + type: stats_notification + frequency: daily + email_to: eric.schallock@sendgrid.com + created_at: 1465595735 + updated_at: 1465595735 security: - Authorization: [] - /mail_settings/footer: - parameters: [] get: - summary: Retrieve footer mail settings - description: |- - **This endpoint allows you to retrieve your current Footer mail settings.** - - The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-footer - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_footer' - examples: - application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - security: - - Authorization: [] - patch: - summary: Update footer mail settings + tags: + - Alerts + summary: Retrieve all alerts description: |- - **This endpoint allows you to update your current Footer mail settings.** + **This endpoint allows you to retieve all of your alerts.** - The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-footer - consumes: - - application/json + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: GET_alerts + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_footer' - example: - enabled: true - html_content: ... - plain_content: ... + - name: Authorization + in: header + description: '' + type: string responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_footer' - examples: - application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content + type: array + description: The list of alerts. + items: + type: object + properties: + created_at: + type: integer + description: A Unix timestamp indicating when the alert was created. + email_to: + type: string + description: The email address that the alert will be sent to. + id: + type: integer + description: The ID of the alert. + percentage: + type: integer + description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' + type: + type: string + description: The type of alert. + enum: + - usage_limit + - stats_notification + updated_at: + type: integer + description: A Unix timestamp indicating when the alert was last modified. + frequency: + type: string + description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".' + required: + - created_at + - email_to + - id + - type + examples: + application/json: + - created_at: 1451498784 + email_to: reaper@example.com + id: 46 + percentage: 90 + type: usage_limit + updated_at: 1451498784 + - created_at: 1451498812 + email_to: reaper@example.com + frequency: monthly + id: 47 + type: stats_notification + updated_at: 1451498812 + - created_at: 1451520930 + email_to: someone@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451520930 security: - Authorization: [] - /mail_settings/address_whitelist: + /scopes: parameters: [] get: - summary: Retrieve address whitelist mail settings + tags: + - API Key Permissions + summary: Retrieve a list of scopes for which this user has access. description: |- - **This endpoint allows you to retrieve your current email address whitelist settings.** - - The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + **This endpoint returns a list of all scopes that this user has access to.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-address_whitelist - consumes: - - application/json + API Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). + operationId: GET_scopes + consumes: [] produces: - application/json parameters: [] responses: '200': description: '' - schema: - $ref: '#/definitions/mail_settings_address_whitelabel' - examples: - application/json: - enabled: false - list: - - example.com - security: - - Authorization: [] - patch: - summary: Update address whitelist mail settings - description: |- - **This endpoint allows you to update your current email address whitelist settings.** - - The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-address_whitelist - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body schema: type: object properties: - enabled: - type: boolean - description: Indicates if your email address whitelist is enabled. - list: + scopes: type: array - description: 'Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.' + description: The list of scopes for which this user has access. + uniqueItems: true items: type: string - example: - enabled: true - list: - - email1@example.com - - example.com - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_address_whitelabel' + required: + - scopes examples: application/json: - enabled: true - list: - - email1@example.com - security: - - Authorization: [] - /mail_settings/plain_content: - parameters: [] - patch: - summary: Update plain content mail settings - description: |- - **This endpoint allows you to update your current Plain Content mail settings.** - - The plain content setting will automatically convert any plain text emails that you send to HTML before sending. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-plain_content - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: The new setting you would like to use for your Plain Content mail setting. - example: - enabled: false - responses: - '200': + scopes: + - mail.send + - alerts.create + - alerts.read + '401': description: '' schema: type: object properties: - enabled: - type: boolean - description: Indicates if your Plain Content mail setting is enabled. + errors: + type: array + description: This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes. + items: + type: object + properties: + field: + type: 'null' + description: This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required. + message: + type: string + description: Explains why the scopes cannot be returned. + required: + - message + required: + - errors examples: application/json: - enabled: false + errors: + - field: null + message: authorization required security: - Authorization: [] + /user/webhooks/parse/stats: + parameters: [] get: - summary: Retrieve plain content mail settings + tags: + - Stats - Parse Webhook Stats + summary: Retrieves Inbound Parse Webhook statistics. description: |- - **This endpoint allows you to retrieve your current Plain Content mail settings.** + **This endpoint allows you to retrieve the statistics for your Parse Webhook useage.** - The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-plain_content - consumes: - - application/json + There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries). + operationId: GET_user-webhooks-parse-stats + consumes: [] produces: - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if the Plain Content mail setting is enabled. + parameters: + - name: limit + in: query + description: The number of statistics to return on each page. + required: false + type: string + - name: offset + in: query + description: The number of statistics to skip. + required: false + type: string + - name: aggregated_by + in: query + description: 'How you would like the statistics to by grouped. ' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: false + type: string + default: The day the request is made. + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + date: + type: string + description: The date that the stats were collected. + stats: + type: array + description: The Parse Webhook usage statistics. + items: + type: object + properties: + metrics: + type: object + properties: + received: + type: number + description: The number of emails received and parsed by the Parse Webhook. + required: + - received + required: + - date + - stats examples: application/json: - enabled: false + - date: '2015-10-11' + stats: + - metrics: + received: 0 + - date: '2015-10-12' + stats: + - metrics: + received: 0 + - date: '2015-10-13' + stats: + - metrics: + received: 0 + - date: '2015-10-14' + stats: + - metrics: + received: 0 + - date: '2015-10-15' + stats: + - metrics: + received: 0 + - date: '2015-10-16' + stats: + - metrics: + received: 0 + - date: '2015-10-17' + stats: + - metrics: + received: 0 + - date: '2015-10-18' + stats: + - metrics: + received: 0 + - date: '2015-10-19' + stats: + - metrics: + received: 0 + - date: '2015-10-20' + stats: + - metrics: + received: 0 + - date: '2015-10-21' + stats: + - metrics: + received: 0 + - date: '2015-10-22' + stats: + - metrics: + received: 0 + - date: '2015-10-23' + stats: + - metrics: + received: 0 + - date: '2015-10-24' + stats: + - metrics: + received: 0 + - date: '2015-10-25' + stats: + - metrics: + received: 0 + - date: '2015-10-26' + stats: + - metrics: + received: 0 + - date: '2015-10-27' + stats: + - metrics: + received: 0 + - date: '2015-10-28' + stats: + - metrics: + received: 0 + - date: '2015-10-29' + stats: + - metrics: + received: 0 + - date: '2015-10-30' + stats: + - metrics: + received: 0 + - date: '2015-10-31' + stats: + - metrics: + received: 0 + - date: '2015-11-01' + stats: + - metrics: + received: 0 + - date: '2015-11-02' + stats: + - metrics: + received: 0 + - date: '2015-11-03' + stats: + - metrics: + received: 0 + - date: '2015-11-04' + stats: + - metrics: + received: 0 + - date: '2015-11-05' + stats: + - metrics: + received: 0 + - date: '2015-11-06' + stats: + - metrics: + received: 0 + - date: '2015-11-07' + stats: + - metrics: + received: 0 + - date: '2015-11-08' + stats: + - metrics: + received: 0 + - date: '2015-11-09' + stats: + - metrics: + received: 0 + - date: '2015-11-10' + stats: + - metrics: + received: 0 security: - Authorization: [] - /user/account: - parameters: [] + '/ips/{ip_address}': + parameters: + - name: ip_address + in: path + description: The IP address you are retrieving the IP pools for. + required: true + type: string get: - tags: - - Users API - summary: Get a user's account information. + summary: Retrieve all IP pools an IP address belongs to description: |- - **This endpoint allows you to retrieve your user account details.** - - Your user's account information includes the user's account type and reputation. - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + **This endpoint allows you to see which IP pools a particular IP address has been added to.** - For more information about your user profile: + The same IP address can be added to multiple IP pools. - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: GET_user-account - consumes: - - application/json + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + operationId: GET_ips-ip_address + consumes: [] produces: - application/json parameters: [] @@ -1479,131 +1760,205 @@ paths: '200': description: '' schema: - title: GET User Account response type: object properties: - type: + ip: type: string - description: The type of account for this user. - enum: - - free - - paid - reputation: - type: number - description: The sender reputation for this user. + description: The IP address. + subusers: + type: array + description: The subusers that can send email using this IP address. + items: + type: string + rdns: + type: string + description: The reverse DNS record for this IP address. + pools: + type: array + description: The list of IP pools that this IP address belongs to. + items: + type: string + warmup: + type: boolean + description: Indicates if this IP address is currently warming up. + start_date: + type: + - integer + - 'null' + description: The date that the IP address was entered into warmup. + whitelabeled: + type: boolean + description: Indicates if this IP address has been whitelabeled. required: - - type - - reputation + - ip + - subusers + - rdns + - pools + - warmup + - start_date + - whitelabeled examples: application/json: - reputation: 100 - type: paid + ip: 000.00.00.0 + subusers: + - subuser1 + - subuser2 + rdns: o1.em.example.com + pools: + - test1 + warmup: false + start_date: null + whitelabeled: true security: - Authorization: [] - /mail_settings/forward_bounce: + /ips/pools: parameters: [] - patch: - summary: Update forward bounce mail settings + get: + tags: + - IP Pools + summary: Retrieve all IP pools. description: |- - **This endpoint allows you to update your current bounce forwarding mail settings.** + **This endpoint allows you to retreive all of your IP pools.** - Activating this setting allows you to specify an email address to which bounce reports are forwarded. + IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-forward_bounce - consumes: - - application/json + IP pools can only be used with whitelabeled IP addresses. + + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: GET_ips-pools + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_forward_bounce' - example: - enabled: true - email: example@example.com + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_bounce' + type: array + items: + $ref: '#/definitions/ip_pool' examples: application/json: - email: '' - enabled: true + - name: marketing + - name: transactional security: - Authorization: [] - get: - summary: Retrieve forward bounce mail settings + post: + tags: + - IP Pools + summary: Create an IP pool. description: |- - **This endpoint allows you to retrieve your current bounce forwarding mail settings.** + **This endpoint allows you to create an IP pool.** - Activating this setting allows you to specify an email address to which bounce reports are forwarded. + **Each user can create up to 10 different IP pools.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-forward_bounce + IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + + IP pools can only be used with whitelabeled IP addresses. + + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: POST_ips-pools consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name of your new IP pool. + maxLength: 64 + required: + - name + example: + name: marketing responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_bounce' + $ref: '#/definitions/ip_pool' examples: application/json: - enabled: false - email: null + name: marketing security: - Authorization: [] - /mail_settings/forward_spam: + /access_settings/activity: parameters: [] - patch: - summary: Update forward spam mail settings + get: + summary: Retrieve all recent access attempts description: |- - **This endpoint allows you to update your current Forward Spam mail settings.** + **This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.** - Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-forward_spam - consumes: - - application/json + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: GET_access_settings-activity + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_forward_spam' - example: - email: '' - enabled: false + - name: limit + in: query + description: Limits the number of IPs to return. + type: integer + default: 20 responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + type: object + properties: + result: + type: array + items: + type: object + properties: + allowed: + type: boolean + auth_method: + type: string + first_at: + type: integer + ip: + type: string + last_at: + type: integer + location: + type: string examples: application/json: - email: '' - enabled: false + result: + - allowed: false + auth_method: basic + first_at: 1444087966 + ip: 1.1.1.1 + last_at: 1444406672 + location: Australia security: - Authorization: [] + '/access_settings/whitelist/{rule_id}': + parameters: + - name: rule_id + in: path + description: The ID of the whitelisted IP address that you want to retrieve. + required: true + type: string get: - summary: Retrieve forward spam mail settings + summary: Retrieve a specific whitelisted IP description: |- - **This endpoint allows you to retrieve your current Forward Spam mail settings.** + **This endpoint allows you to retreive a specific IP address that has been whitelisted.** - Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + You must include the ID for the specific IP address you want to retrieve in your call. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-forward_spam - consumes: - - application/json + IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: GET_access_settings-whitelist-rule_id + consumes: [] produces: - application/json parameters: [] @@ -1611,54 +1966,56 @@ paths: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + type: object + properties: + created_at: + type: integer + id: + type: integer + ip: + type: string + updated_at: + type: integer examples: application/json: - email: '' - enabled: true + created_at: 1441824715 + id: 1 + ip: 192.168.1.1 + updated_at: 1441824715 security: - Authorization: [] - /mail_settings/template: - parameters: [] - get: - summary: Retrieve legacy template mail settings + delete: + summary: Remove a specific IP from the whitelist description: |- - **This endpoint allows you to retrieve your current legacy email template settings.** + **This endpoint allows you to remove a specific IP address from your IP whitelist.** - This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + When removing a specific IP address from your whitelist, you must include the ID in your call. - The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. + IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-template - consumes: - - application/json - produces: - - application/json + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: DELETE_access_settings-whitelist-rule_id + consumes: [] + produces: [] parameters: [] responses: - '200': + '204': description: '' - schema: - $ref: '#/definitions/mail_settings_template' - examples: - application/json: - enabled: false - html_content: | -

<% body %>Example

security: - Authorization: [] - patch: - summary: Update template mail settings + /access_settings/whitelist: + parameters: [] + post: + summary: Add one or more IPs to the whitelist description: |- - **This endpoint allows you to update your current legacy email template settings.** + **This endpoint allows you to add one or more IP addresses to your IP whitelist.** - This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once. - The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. + IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-template + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: POST_access_settings-whitelist consumes: - application/json produces: @@ -1669,343 +2026,250 @@ paths: schema: type: object properties: - enabled: - type: boolean - description: Indicates if you want to enable the legacy email template mail setting. - html_content: - type: string - description: The new HTML content for your legacy email template. + ips: + type: array + description: An array containing the IP(s) you want to whitelist. + items: + type: object + properties: + ip: + type: string + description: An IP address that you want to whitelist. + required: + - ip + required: + - ips example: - enabled: true - html_content: <% body %> + ips: + - ip: 192.168.1.1 + - ip: 192.*.*.* + - ip: 192.168.1.3/32 responses: - '200': + '201': description: '' schema: type: object properties: - enabled: - type: boolean - html_content: - type: string - examples: - application/json: - enabled: false - html_content: | -

<% body %>Example

- security: - - Authorization: [] - '/campaigns/{campaign_id}/schedules': - parameters: - - name: campaign_id - in: path - required: true - type: integer - get: - summary: View Scheduled Time of a Campaign - description: |- - **This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.** - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: GET_campaigns-campaign_id-schedules - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - title: View Scheduled Time of a Campaign response - type: object - properties: - send_at: - type: integer - format: int64 - required: - - send_at - examples: - application/json: - send_at: 1490778528 - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + result: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: integer + ip: + type: string + updated_at: + type: integer examples: application/json: - errors: - - field: null - message: not found + result: + - created_at: 1441824715 + id: 1 + ip: 192.168.1.1/32 + updated_at: 1441824715 security: - Authorization: [] delete: - summary: Unschedule a Scheduled Campaign + summary: Remove one or more IPs from the whitelist description: |- - **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** + **This endpoint allows you to remove one or more IPs from your IP whitelist.** - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + You can remove one IP at a time, or you can remove multiple IP addresses. - For more information: + IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: DELETE_campaigns-campaign_id-schedules + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: DELETE_access_settings-whitelist consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: - type: 'null' + type: object + properties: + ids: + type: array + description: An array of the IDs of the IP address that you want to remove from your whitelist. + items: + type: integer + example: + ids: + - 1 + - 2 + - 3 responses: '204': description: '' - schema: - type: 'null' - '403': - description: |- - "": "This campaign is already In Progress." - "": "This campaign is already Sent." - "": "This campaign is already Paused." - "": "This campaign is already Canceled." - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: This campaign is already In Progress. - - field: null - message: This campaign is already Sent. - - field: null - message: This campaign is already Paused. - - field: null - message: This campaign is already Canceled. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found security: - Authorization: [] - patch: - summary: Update a Scheduled Campaign + get: + summary: Retrieve a list of currently whitelisted IPs description: |- - **This endpoint allows to you change the scheduled time and date for a campaign to be sent.** + **This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.** - For more information: + IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: PATCH_campaigns-campaign_id-schedules - consumes: - - application/json + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: GET_access_settings-whitelist + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - title: Update a Scheduled Campaign request - type: object - properties: - send_at: - type: integer - format: int64 - required: - - send_at - example: - send_at: 1489451436 + parameters: [] responses: '200': description: '' schema: - title: Update a Scheduled Campaign response type: object properties: - id: - type: integer - description: The campaign ID - send_at: - type: integer - description: The unix timestamp to send the campaign. - status: - type: string - description: The status of the schedule. - required: - - id - - send_at - - status - '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "send_at": "Please choose a future time for sending your campaign." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: send_at - message: Please choose a future time for sending your campaign. - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing' - '403': - description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: send_at - message: You cannot update the send_at value of non-scheduled campaign. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + result: + type: array + items: + type: object + properties: + created_at: + type: integer + id: + type: integer + ip: + type: string + updated_at: + type: integer examples: application/json: - errors: - - field: null - message: not found + result: + - created_at: 1441824715 + id: 1 + ip: 192.168.1.1/32 + updated_at: 1441824715 security: - Authorization: [] - post: - summary: Schedule a Campaign + /subusers/stats/monthly: + parameters: [] + get: + tags: + - Stats - Subuser Stats + summary: Retrieve monthly stats for all subusers description: |- - **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** + **This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** - For more information: + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns-campaign_id-schedules - consumes: - - application/json + 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`. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: GET_subusers-stats-monthly + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - title: Schedule a Campaign request - type: object - properties: - send_at: - type: integer - description: The unix timestamp for the date and time you would like your campaign to be sent out. - required: - - send_at - example: - send_at: 1489771528 - responses: - '201': - description: '' - schema: - title: Schedule a Campaign response - type: object - properties: - id: - type: integer - description: The campaign ID. - send_at: - type: integer - description: The date time you scheduled your campaign to be sent. - status: - type: string - description: The status of your campaign. - enum: - - Scheduled - required: - - id - - send_at - - status - examples: - application/json: - id: 1234 - send_at: 1489771528 - status: Scheduled - '400': - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "send_at": "Please choose a future time for sending your campaign." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "The JSON you have submitted cannot be parsed." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: subject - message: subject can't be blank - - field: sender_id - message: sender_id can't be blank - - field: plain_content - message: 'plain_content can''t be blank, please provide plain text or html content' - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '401': + - name: date + in: query + description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD + required: true + type: string + - name: subuser + in: query + description: A substring search of your subusers. + required: false + 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 + type: string + default: delivered + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + default: desc + enum: + - desc + - asc + - name: limit + in: query + description: Optional field to limit the number of results returned. + required: false + type: integer + default: 5 + - name: offset + in: query + description: Optional beginning point in the list to retrieve from. + required: false + type: integer + default: 0 + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/subuser_stats' examples: application/json: - errors: - - field: null - message: not found + 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 security: - Authorization: [] - /contactdb/lists: + /user/settings/enforced_tls: parameters: [] get: - tags: - - Contacts API - Lists - summary: Retrieve all lists + summary: Retrieve current Enforced TLS settings. description: |- - **This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.** + **This endpoint allows you to retrieve your current Enforced TLS settings.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-lists - consumes: - - application/json + The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. + + **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. + operationId: GET_user-settings-enforced_tls + consumes: [] produces: - application/json parameters: [] @@ -2013,32 +2277,32 @@ paths: '200': description: '' schema: - title: List All Lists response type: object properties: - lists: - type: array - items: - $ref: '#/definitions/contactdb_list' + require_tls: + type: boolean + description: Indicates if the recipient is required to support TLS. + require_valid_cert: + type: boolean + description: Indicates if the recipient is required to have a valid certificate. required: - - lists + - require_tls + - require_valid_cert examples: application/json: - lists: - - id: 1 - name: the jones - recipient_count: 1 + require_tls: false + require_valid_cert: false security: - Authorization: [] - delete: - tags: - - Contacts API - Lists - summary: Delete Multiple lists + patch: + summary: Update Enforced TLS settings description: |- - **This endpoint allows you to delete multiple recipient lists.** + **This endpoint allows you to update your current Enforced TLS settings.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: DELETE_contactdb-lists + The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. + + **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. + operationId: PATCH_user-settings-enforced_tls consumes: - application/json produces: @@ -2047,120 +2311,175 @@ paths: - name: body in: body schema: - type: array - items: - type: number + type: object + properties: + require_tls: + type: boolean + description: 'Indicates if you want to require your recipients to support TLS. ' + require_valid_cert: + type: boolean + description: Indicates if you want to require your recipients to have a valid certificate. example: - - 1 - - 2 - - 3 - - 4 + require_tls: true + require_valid_cert: false responses: - '204': - description: '' - schema: - type: 'null' - '400': - description: '"id" : "Returned if all list ids are not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: list id was invalid - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + require_tls: + type: boolean + description: Indicates if your recipients are required to support TLS. + require_valid_cert: + type: boolean + description: Indicates if your recipients are required to have a valid certificate. + required: + - require_tls + - require_valid_cert examples: application/json: - errors: - - field: null - message: authorization required + require_tls: true + require_valid_cert: false security: - Authorization: [] - post: - tags: - - Contacts API - Lists - summary: Create a List + '/ips/pools/{pool_name}/ips/{ip}': + parameters: + - name: pool_name + in: path + description: The name of the IP pool that you are removing the IP address from. + required: true + type: string + - name: ip + in: path + description: The IP address that you are removing. + required: true + type: string + delete: + summary: Remove an IP address from a pool. description: |- - **This endpoint allows you to create a list for your recipients.** + **This endpoint allows you to remove an IP address from an IP pool.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: POST_contactdb-lists - consumes: - - application/json + The same IP address can be added to multiple IP pools. + + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + operationId: DELETE_ips-pools-pool_name-ips-ip + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - title: Create a List request - type: object - properties: - name: - type: string - required: - - name - example: - name: your list name + parameters: [] responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/contactdb_list' - examples: - application/json: - id: 1 - name: your list name - recipient_count: 0 - '400': - description: |- - "name" : "Returned if list name is a duplicate of an existing list or segment" - "name" : "Returned if list name is not a string" - "" : "Returned if request body is invalid JSON" + type: object + '404': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + error: + type: string + description: An error explaining why the IP address could not be removed from the IP pool. examples: application/json: - errors: - - field: null - message: Returned if request body is invalid JSON - - field: name - message: Returned if list name is not a string - - field: name - message: Returned if list name is a duplicate of an existing list or segment - '401': + error: Unable to locate specified IPs Pool + security: + - Authorization: [] + /user/credits: + parameters: [] + get: + tags: + - Users API + summary: Retrieve your credit balance + description: |- + **This endpoint allows you to retrieve the current credit balance for your account.** + + Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html). + operationId: GET_user-credits + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + remain: + type: integer + description: The remaining number of credits available on your account. + total: + type: integer + description: The total number of credits assigned to your account. + overage: + type: integer + description: The number of overdrawn credits for your account. + used: + type: integer + description: The number of credits that you have used. + last_reset: + type: string + description: The date that your credit balance was last reset. + next_reset: + type: string + description: The next date that your credit balance will be reset. + reset_frequency: + type: string + description: The frequency at which your credit balance will be reset. + required: + - remain + - total + - overage + - used + - last_reset + - next_reset + - reset_frequency examples: application/json: - errors: - - field: null - message: authorization required + remain: 200 + total: 200 + overage: 0 + used: 0 + last_reset: '2013-01-01' + next_reset: '2013-02-01' + reset_frequency: monthly security: - Authorization: [] - '/campaigns/{campaign_id}': + '/templates/{template_id}': parameters: - - name: campaign_id + - name: template_id in: path - description: The ID of the campaign that you would like to delete. + description: The id of the transactional template you want to delete. required: true - type: integer + type: string delete: - summary: Delete a Campaign - description: |- - **This endpoint allows you to delete a specific campaign.** + summary: Delete a template. + description: | + **This endpoint allows you to delete a transactional template.** - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - For more information: + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: DELETE_templates-template_id + consumes: [] + produces: [] + parameters: [] + responses: + '204': + description: '' + security: + - Authorization: [] + patch: + summary: Edit a transactional template. + description: | + **This endpoint allows you to edit a transactional template.** - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: DELETE_campaigns-campaign_id + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: PATCH_templates-template_id consumes: - application/json produces: @@ -2169,40 +2488,36 @@ paths: - name: body in: body schema: - type: 'null' + type: object + properties: + name: + type: string + description: The name of the transactional template. + maxLength: 100 + example: + name: new_example_name responses: - '204': - description: '' - schema: - type: 'null' - '401': + '200': description: '' schema: - type: object + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - field: null - message: authorization required - '404': - description: '"": "not found"' - schema: - type: object + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: new_example_name + versions: [] security: - Authorization: [] get: - summary: Retrieve a single campaign - description: |- - **This endpoint allows you to retrieve a specific campaign.** - - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + summary: Retrieve a single transactional template. + description: | + **This endpoint allows you to retrieve a single transactional template.** - For more information: + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: GET_campaigns-campaign_id - consumes: - - application/json + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: GET_templates-template_id + consumes: [] produces: - application/json parameters: [] @@ -2210,55 +2525,81 @@ paths: '200': description: '' schema: - $ref: '#/definitions/campaign_response' - examples: - application/json: - id: 986724 - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Check out our spring line!

- plain_content: Check out our spring line! - status: Draft - '401': + $ref: '#/definitions/transactional_template' + security: + - Authorization: [] + '/alerts/{alert_id}': + parameters: + - name: alert_id + in: path + description: The ID of the alert you would like to retrieve. + required: true + type: integer + get: + summary: Retrieve a specific alert + description: |- + **This endpoint allows you to retrieve a specific alert.** + + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: GET_alerts-alert_id + consumes: [] + produces: + - application/json + - text/plain + parameters: + - name: Authorization + in: header + description: '' + type: string + responses: + '200': description: '' schema: type: object examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"": "not found"' - schema: - type: object - examples: - application/json: - errors: - - field: null - message: not found + text/plain: + id: 304575 + type: stats_notification + frequency: daily + email_to: eric.schallock@sendgrid.com + created_at: 1465613735 + updated_at: 1465595735 + security: + - Authorization: [] + delete: + summary: Delete an alert + description: |- + **This endpoint allows you to delete an alert.** + + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: DELETE_alerts-alert_id + consumes: [] + produces: [] + parameters: [] + responses: + '204': + description: '' security: - Authorization: [] patch: - summary: Update a Campaign + summary: Update an alert description: |- - Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. + **This endpoint allows you to update an alert.** - For more information: + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: PATCH_campaigns-campaign_id + For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + operationId: PATCH_alerts-alert_id consumes: - application/json produces: @@ -2267,184 +2608,118 @@ paths: - name: body in: body schema: - title: Update a Campaign request type: object properties: - title: - type: string - description: The title of the campaign. - subject: - type: string - description: The subject line for your campaign. - categories: - type: array - description: The categories you want to tag on this campaign. - items: - type: string - html_content: + email_to: type: string - description: The HTML content of this campaign. - plain_content: + description: |- + The new email address you want your alert to be sent to. + Example: test@example.com + frequency: type: string - description: The plain content of this campaign. - required: - - title - - subject - - categories - - html_content - - plain_content + description: |- + The new frequency at which to send the stats_notification alert. + Example: monthly + percentage: + type: integer + description: |- + The new percentage threshold at which the usage_limit alert will be sent. + Example: 90 example: - title: May Newsletter - subject: New Products for Summer! - categories: - - summer line - html_content:

Check out our summer line!

- plain_content: Check out our summer line! + email_to: test@example.com responses: '200': description: '' - schema: - $ref: '#/definitions/campaign_response' - examples: - application/json: - id: 986724 - title: May Newsletter - subject: New Products for Summer! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - summer line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Check out our summer line!

- plain_content: Check out our summer line! - status: Draft - '400': - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - schema: - type: object - examples: - application/json: - errors: - - field: title - message: title can't be blank - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You may only update a campaign when it is in draft mode."' schema: type: object + properties: + created_at: + type: integer + description: A Unix timestamp indicating when the alert was created. + email_to: + type: string + description: The email address that the alert will be sent to. + frequency: + type: string + description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".' + id: + type: integer + description: The ID of the alert. + type: + type: string + description: The type of alert. + enum: + - usage_alert + - stats_notification + updated_at: + type: integer + description: A Unix timestamp indicating when the alert was last modified. + percentage: + type: integer + description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' + required: + - created_at + - email_to + - id + - type + - updated_at examples: application/json: - errors: - - field: null - message: You may only update a campaign when it is in draft mode. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + created_at: 1451520930 + email_to: test@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451522691 security: - Authorization: [] - /contactdb/recipients/count: + /user/webhooks/parse/settings: parameters: [] - get: + post: tags: - - Contacts API - Recipients - summary: Retrieve a Count of Recipients + - Settings - Inbound Parse + summary: Create a parse setting description: |- - **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.** + **This endpoint allows you to create a new inbound parse setting.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-recipients-count + The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + operationId: POST_user-webhooks-parse-settings consumes: - application/json produces: - application/json - parameters: [] - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: - $ref: '#/definitions/contactdb_recipient_count' - examples: - application/json: - recipient_count: 1234 - '401': + $ref: '#/definitions/parse-setting' + example: + hostname: myhostname.com + url: 'http://email.myhosthame.com' + spam_check: true + send_raw: false + responses: + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/parse-setting' examples: application/json: - errors: - - field: null - message: authorization required + url: 'http://email.myhostname.com' + hostname: myhostname.com + spam_check: false + send_raw: true security: - Authorization: [] - '/whitelabel/domains/{domain_id}': - parameters: [] get: - summary: Retrieve a domain whitelabel. - description: | - **This endpoint allows you to retrieve a specific domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + tags: + - Settings - Inbound Parse + summary: Retrieve all parse settings + description: |- + **This endpoint allows you to retrieve all of your current inbound parse settings.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - operationId: GET_whitelabel-domains-domain_id + The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + operationId: GET_user-webhooks-parse-settings consumes: - application/json produces: @@ -2454,120 +2729,126 @@ paths: '200': description: '' schema: - $ref: '#/definitions/whitelabel::domain' + type: object + properties: + result: + type: array + description: The list of your current inbound parse settings. + items: + $ref: '#/definitions/parse-setting' + examples: + application/json: + result: + - url: 'http://mydomain.com/parse' + hostname: mail.mydomain.com + spam_check: true + send_raw: true security: - Authorization: [] - delete: - summary: Delete a domain whitelabel. + '/user/webhooks/parse/settings/{hostname}/': + parameters: + - name: hostname + in: path + description: The hostname associated with the specific inbound parse setting that you want to update. + required: true + type: string + patch: + summary: Update a parse setting description: |- - **This endpoint allows you to delete a domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to update a specific inbound parse setting.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - operationId: DELETE_whitelabel-domains-domain_id + The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + operationId: PATCH_user-webhooks-parse-settings-hostname consumes: - application/json - produces: [] + produces: + - application/json parameters: - name: body in: body schema: - type: 'null' + $ref: '#/definitions/parse-setting' + example: + url: 'http://newdomain.com/parse' + spam_check: false + send_raw: true responses: - '204': + '200': description: '' schema: - type: object + $ref: '#/definitions/parse-setting' + examples: + application/json: + url: 'http://mydomain.com/parse' + hostname: mail.mydomain.com + spam_check: true + send_raw: true security: - Authorization: [] - patch: - summary: Update a domain whitelabel. + '/user/webhooks/parse/settings/{hostname}': + parameters: + - name: hostname + in: path + description: The hostname associated with the inbound parse setting that you want to delete. + required: true + type: string + delete: + tags: + - Settings - Inbound Parse + summary: Delete a parse setting description: |- - **This endpoint allows you to update the settings for a domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to delete a specific inbound parse setting.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - operationId: PATCH_whitelabel-domains-domain_id + The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + operationId: DELETE_user-webhooks-parse-settings-hostname consumes: - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - default: - type: boolean - default: false - description: Indicates whether this domain whitelabel should be considered the default. - custom_spf: - type: boolean - default: false - description: Indicates whether to generate a custom SPF record for manual security. - example: - default: false - custom_spf: true + produces: [] + parameters: [] responses: - '200': + '204': description: '' - schema: - title: Update a Domain response - type: object - properties: - default false: - description: Inidcates whether this domain whitelabel should be considered the default. Defaults to false. - type: boolean - custom_spf false: - description: Indicates whether to generate a custom SPF record for manual security. Defaults to false. - type: boolean security: - Authorization: [] - '/templates/{template_id}': - parameters: - - name: template_id - in: path - description: The id of the transactional template you want to delete. - required: true - type: string - delete: - summary: Delete a template. - description: | - **This endpoint allows you to delete a transactional template.** - - Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + get: + tags: + - Settings - Inbound Parse + summary: Retrieve a specific parse setting + description: |- + **This endpoint allows you to retrieve a specific inbound parse setting.** - Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - operationId: DELETE_templates-template_id + The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + operationId: GET_user-webhooks-parse-settings-hostname consumes: - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' + produces: + - application/json + parameters: [] responses: - '204': + '200': description: '' schema: - type: object + $ref: '#/definitions/parse-setting' + examples: + application/json: + url: 'http://mydomain.com/parse' + hostname: mail.mydomain.com + spam_check: true + send_raw: true security: - Authorization: [] + '/subusers/{subuser_name}/monitor': + parameters: + - name: subuser_name + in: path + description: The name of the subuser for which to retrieve monitor settings. + required: true + type: string get: - summary: Retrieve a single transactional template. - description: | - **This endpoint allows you to retrieve a single transactional template.** - - Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - - Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - operationId: GET_templates-template_id - consumes: - - application/json + summary: Retrieve monitor settings for a subuser + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: GET_subusers-subuser_name-monitor + consumes: [] produces: - application/json parameters: [] @@ -2575,18 +2856,35 @@ paths: '200': description: '' schema: - $ref: '#/definitions/transactional_template' + $ref: '#/definitions/monitor' + examples: + application/json: + email: example@example.com + frequency: 500 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: No monitor settings for this user security: - Authorization: [] - patch: - summary: Edit a transactional template. - description: | - **This endpoint allows you to edit a transactional template.** - - Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - - Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - operationId: PATCH_templates-template_id + put: + summary: Update Monitor Settings for a subuser + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: PUT_subusers-subuser_name-monitor consumes: - application/json produces: @@ -2595,62 +2893,43 @@ paths: - name: body in: body schema: - type: object - properties: - name: - type: string - description: The name of the transactional template. - maxLength: 100 + $ref: '#/definitions/monitor' example: - name: new_example_name + email: example@example.com + frequency: 500 responses: '200': description: '' schema: - $ref: '#/definitions/transactional_template' + $ref: '#/definitions/monitor' examples: application/json: - id: 733ba07f-ead1-41fc-933a-3976baa23716 - name: new_example_name - versions: [] - security: - - Authorization: [] - /mail_settings/bcc: - parameters: [] - get: - summary: Retrieve all BCC mail settings - description: |- - **This endpoint allows you to retrieve your current BCC mail settings.** - - When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-bcc - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': + email: example@example.com + frequency: 500 + '400': description: '' schema: - $ref: '#/definitions/mail_settings_bcc' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - email: example@example.com - enabled: false + errors: + - field: email + message: Email is required + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required security: - Authorization: [] - patch: - summary: Update BCC mail settings - description: |- - **This endpoint allows you to update your current BCC mail settings.** - - When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-bcc + post: + summary: Create monitor settings + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: POST_subusers-subuser_name-monitor consumes: - application/json produces: @@ -2659,45 +2938,28 @@ paths: - name: body in: body schema: - $ref: '#/definitions/mail_settings_patch' + $ref: '#/definitions/monitor' example: - enabled: false - email: email@example.com + email: example@example.com + frequency: 50000 responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_patch' + $ref: '#/definitions/monitor' examples: application/json: email: example@example.com - enabled: false - security: - - Authorization: [] - /contactdb/recipients/billable_count: - parameters: [] - get: - summary: Retrieve the count of billable recipients - description: |- - **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** - - You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-recipients-billable_count - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': + frequency: 50000 + '400': description: '' schema: - $ref: '#/definitions/contactdb_recipient_count' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - recipient_count: 1234 + errors: + - field: null + message: User already has a monitor '401': description: '' schema: @@ -2709,43 +2971,49 @@ paths: message: authorization required security: - Authorization: [] - /partner_settings/new_relic: - parameters: [] - get: - summary: Returns all New Relic partner settings. - description: |- - **This endpoint allows you to retrieve your current New Relic partner settings.** - - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). - - By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). - operationId: GET_partner_settings-new_relic - consumes: - - application/json + delete: + summary: Delete monitor settings + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: DELETE_subusers-subuser_name-monitor + consumes: [] produces: - application/json parameters: [] responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/partner_settings_new_relic' + type: object + properties: {} + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enable_subuser_statistics: false - enabled: true - license_key: '' - security: - - Authorization: [] - patch: - summary: Updates New Relic partner settings. - description: |- - **This endpoint allows you to update or change your New Relic partner settings.** - - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + errors: + - field: null + message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: No monitor settings for this user + /contactdb/lists: + parameters: [] + delete: + tags: + - Contacts API - Lists + summary: Delete Multiple lists + description: |- + **This endpoint allows you to delete multiple recipient lists.** - By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). - operationId: PATCH_partner_settings-new_relic + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: DELETE_contactdb-lists consumes: - application/json produces: @@ -2754,75 +3022,48 @@ paths: - name: body in: body schema: - type: object - properties: - license_key: - type: string - description: The license key for your New Relic account. - enabled: - type: boolean - description: Indicates if this partner setting is enabled. - enable_subuser_statistics: - type: boolean - description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. + type: array + items: + type: integer example: - license_key: '' - enabled: true - enable_subuser_statistics: true + - 1 + - 2 + - 3 + - 4 responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/partner_settings_new_relic' + type: 'null' + '400': + description: '"id" : "Returned if all list ids are not valid"' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enable_subuser_statistics: true - enabled: true - license_key: '' - security: - - Authorization: [] - '/asm/groups/{group_id}/suppressions': - parameters: - - name: group_id - in: path - description: The id of the suppression group that you are retrieving email addresses from. - required: true - type: string - get: - summary: Retrieve all suppressions for a suppression group - description: |- - **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.** - - Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. - operationId: GET_asm-groups-group_id-suppressions - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': + errors: + - field: null + message: list id was invalid + '401': description: '' schema: - type: array - description: The list of email addresses belonging to the given suppression group. - items: - type: string + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - example@example.com - - example2@example.com + errors: + - field: null + message: authorization required security: - Authorization: [] post: - summary: Add suppressions to a suppression group + tags: + - Contacts API - Lists + summary: Create a List description: |- - **This endpoint allows you to add email addresses to an unsubscribe group.** - - If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. + **This endpoint allows you to create a list for your recipients.** - Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. - operationId: POST_asm-groups-group_id-suppressions + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: POST_contactdb-lists consumes: - application/json produces: @@ -2831,88 +3072,62 @@ paths: - name: body in: body schema: + title: Create a List request type: object properties: - recipient_emails: - type: array - description: The email address that you want to add to the unsubscribe group. - items: - type: string + name: + type: string required: - - recipient_emails + - name example: - recipient_emails: - - test1@example.com - - test2@example.com + name: your list name responses: '201': description: '' schema: - type: object - properties: - recipient_emails: - type: array - description: The email address that were added to the suppressions list. - items: - type: string - required: - - recipient_emails + $ref: '#/definitions/contactdb_list' examples: application/json: - recipient_emails: - - test1@example.com - - test2@example.com - security: - - Authorization: [] - '/asm/groups/{group_id}/suppressions/{email}': - parameters: - - name: group_id - in: path - description: The id of the suppression group that you are removing an email address from. - required: true - type: string - - name: email - in: path - description: The email address that you want to remove from the suppression group. - required: true - type: string - delete: - summary: Delete a suppression from a suppression group - description: |- - **This endpoint allows you to remove a suppressed email address from the given suppression group.** - - Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. - operationId: DELETE_asm-groups-group_id-suppressions-email - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body + id: 1 + name: your list name + recipient_count: 0 + '400': + description: |- + "name" : "Returned if list name is a duplicate of an existing list or segment" + "name" : "Returned if list name is not a string" + "" : "Returned if request body is invalid JSON" schema: - type: 'null' - responses: - '204': + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: Returned if request body is invalid JSON + - field: name + message: Returned if list name is not a string + - field: name + message: Returned if list name is a duplicate of an existing list or segment + '401': description: '' schema: - type: 'null' + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required security: - Authorization: [] - /templates: - parameters: [] get: tags: - - Transactional Templates - summary: Retrieve all transactional templates. + - Contacts API - Lists + summary: Retrieve all lists description: |- - **This endpoint allows you to retrieve all transactional templates.** - - Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + **This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.** - Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - operationId: GET_templates - consumes: - - application/json + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-lists + consumes: [] produces: - application/json parameters: [] @@ -2920,3470 +3135,79 @@ paths: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/transactional_template' - security: - - Authorization: [] - post: - tags: - - Transactional Templates - summary: Create a transactional template. - description: |- - **This endpoint allows you to create a transactional template.** - - Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - - Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - operationId: POST_templates - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: + title: List All Lists response type: object properties: - name: - type: string - description: The name for the new transactional template. - maxLength: 100 + lists: + type: array + items: + $ref: '#/definitions/contactdb_list' required: - - name - example: - name: example_name - responses: - '201': - description: '' - schema: - $ref: '#/definitions/transactional_template' + - lists examples: application/json: - id: 733ba07f-ead1-41fc-933a-3976baa23716 - name: example_name - versions: [] + lists: + - id: 1 + name: the jones + recipient_count: 1 security: - Authorization: [] - /ips/pools: + /mailbox_providers/stats: parameters: [] - post: - tags: - - IP Pools - summary: Create an IP pool. - description: |- - **This endpoint allows you to create an IP pool.** - - **Each user can create up to 10 different IP pools.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: POST_ips-pools - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The name of your new IP pool. - maxLength: 64 - required: - - name - example: - name: marketing - responses: - '200': - description: '' - schema: - $ref: '#/definitions/ip_pool' - examples: - application/json: - name: marketing - security: - - Authorization: [] get: - tags: - - IP Pools - summary: Retrieve all IP pools. + summary: Retrieve email statistics by mailbox provider. description: |- - **This endpoint allows you to retreive all of your IP pools.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + **This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.** - IP pools can only be used with whitelabeled IP addresses. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: GET_ips-pools - consumes: - - application/json + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_mailbox_providers-stats + consumes: [] produces: - application/json - parameters: [] + parameters: + - name: limit + in: query + description: The number of results to include on each page. + required: false + type: integer + - name: offset + in: query + description: The number of results to exclude. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the stats. Must be either "day", "wee", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + 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 + type: string + - name: mailbox_providers + in: query + description: The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times. + required: false + type: string responses: '200': description: '' schema: type: array items: - $ref: '#/definitions/ip_pool' - examples: - application/json: - - name: marketing - - name: transactional - security: - - Authorization: [] - /mail_settings/spam_check: - parameters: [] - get: - summary: Retrieve spam check mail settings - description: |- - **This endpoint allows you to retrieve your current Spam Checker mail settings.** - - The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-spam_check - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_spam_check' - examples: - application/json: - enabled: false - max_score: 6 - url: 'http://example.com' - security: - - Authorization: [] - patch: - summary: Update spam check mail settings - description: |- - **This endpoint allows you to update your current spam checker mail settings.** - - The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-spam_check - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if you want the spam check mail setting to be enabled or not. - url: - type: string - description: The Inbound Parse URL where you would like your spam reports to be sent to. - max_score: - type: integer - default: 5 - description: 'The new max score, or spam threshold that you would like to set for the spam checker.' - minimum: 1 - maximum: 10 - example: - enabled: true - url: url - max_score: 5 - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_spam_check' - examples: - application/json: - enabled: false - max_score: 6 - url: 'http://example.com' - security: - - Authorization: [] - /tracking_settings/click: - parameters: [] - get: - summary: Retrieve Click Track Settings - description: |- - **This endpoint allows you to retrieve your current click tracking setting.** - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: GET_tracking_settings-click - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - enable_text: - type: boolean - description: Indicates if click tracking is enabled for plain text emails. - enabled: - type: boolean - description: Indicates if click tracking is enabled or disabled. - required: - - enable_text - - enabled - examples: - application/json: - enable_text: false - enabled: true - security: - - Authorization: [] - patch: - summary: Update Click Tracking Settings - description: |- - **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: PATCH_tracking_settings-click - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: The setting you want to use for click tracking. - example: - enabled: true - responses: - '200': - description: '' - schema: - type: object - properties: - enable_text: - type: boolean - description: Indicates if click tracking is enabled for plain text emails - enabled: - type: boolean - description: The new setting new setting for click tracking. - required: - - enable_text - - enabled - examples: - application/json: - enable_text: false - enabled: true - security: - - Authorization: [] - /whitelabel/links: - parameters: [] - post: - tags: - - Whitelabel - Links - summary: Create a Link Whitelabel - description: |- - **This endpoint allows you to create a new link whitelabel.** - - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: POST_whitelabel-links - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: Number of domains to return. - type: integer - default: 50 - - name: offset - in: query - description: Paging offset. - type: integer - default: 0 - - name: body - in: body - schema: - type: object - properties: - domain: - type: string - description: The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address. - subdomain: - type: string - description: The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel. - default: - type: boolean - description: 'Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.' - enum: - - true - - false - required: - - domain - - subdomain - example: - domain: example.com - subdomain: mail - default: true - responses: - '201': - description: '' - schema: - $ref: '#/definitions/link_whitelabel' - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - security: - - Authorization: [] - get: - tags: - - Whitelabel - Links - summary: Retrieve all link whitelabels - description: |- - **This endpoint allows you to retrieve all link whitelabels.** - - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: GET_whitelabel-links - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: Limits the number of results returned per page. - type: integer - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/link_whitelabel' - examples: - application/json: - - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: true - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - - id: 2 - domain: example2.com - subdomain: news - username: john@example.com - user_id: 8 - default: false - valid: false - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: news.example2.com - data: sendgrid.net - owner_cname: - valid: false - type: cname - host: 8.example2.com - data: sendgrid.net - security: - - Authorization: [] - '/asm/suppressions/global/{email}': - parameters: - - name: email - in: path - description: The email address you want to remove from the global suppressions group. - required: true - type: string - delete: - tags: - - Suppression Management - Global Suppressions - summary: Delete a Global Suppression - description: |- - **This endpoint allows you to remove an email address from the global suppressions group.** - - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: DELETE_asm-suppressions-global-email - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - security: - - Authorization: [] - get: - tags: - - Suppression Management - Global Suppressions - summary: Retrieve a Global Suppression - description: |- - **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** - - If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned. - - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: GET_asm-suppressions-global-email - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - title: Retrieve a Global Suppression response - type: object - properties: - recipient_email: - type: string - description: The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed. - required: - - recipient_email - security: - - Authorization: [] - /scopes: - parameters: [] - get: - tags: - - API Key Permissions - summary: Retrieve a list of scopes for which this user has access. - description: |- - **This endpoint returns a list of all scopes that this user has access to.** - - API Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). - operationId: GET_scopes - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - scopes: - type: array - description: The list of scopes for which this user has access. - uniqueItems: true - items: - type: string - required: - - scopes - examples: - application/json: - scopes: - - mail.send - - alerts.create - - alerts.read - '401': - description: '' - schema: - type: object - properties: - errors: - type: array - description: This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes. - items: - type: object - properties: - field: - type: 'null' - description: This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required. - message: - type: string - description: Explains why the scopes cannot be returned. - required: - - message - required: - - errors - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - /user/webhooks/parse/stats: - parameters: [] - get: - tags: - - Stats - Parse Webhook Stats - summary: Retrieves Inbound Parse Webhook statistics. - description: |- - **This endpoint allows you to retrieve the statistics for your Parse Webhook useage.** - - SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. - - There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries). - operationId: GET_user-webhooks-parse-stats - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: The number of statistics to return on each page. - required: false - type: string - - name: offset - in: query - description: The number of statistics to skip. - required: false - type: string - - name: aggregated_by - in: query - description: 'How you would like the statistics to by grouped. ' - required: false - type: string - enum: - - day - - week - - month - - name: start_date - in: query - description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD - required: true - type: string - - name: end_date - in: query - description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD - required: false - type: string - default: The day the request is made. - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - date: - type: string - description: The date that the stats were collected. - stats: - type: array - description: The Parse Webhook usage statistics. - items: - type: object - properties: - metrics: - type: object - properties: - received: - type: number - description: The number of emails received and parsed by the Parse Webhook. - required: - - received - required: - - date - - stats - examples: - application/json: - - date: '2015-10-11' - stats: - - metrics: - received: 0 - - date: '2015-10-12' - stats: - - metrics: - received: 0 - - date: '2015-10-13' - stats: - - metrics: - received: 0 - - date: '2015-10-14' - stats: - - metrics: - received: 0 - - date: '2015-10-15' - stats: - - metrics: - received: 0 - - date: '2015-10-16' - stats: - - metrics: - received: 0 - - date: '2015-10-17' - stats: - - metrics: - received: 0 - - date: '2015-10-18' - stats: - - metrics: - received: 0 - - date: '2015-10-19' - stats: - - metrics: - received: 0 - - date: '2015-10-20' - stats: - - metrics: - received: 0 - - date: '2015-10-21' - stats: - - metrics: - received: 0 - - date: '2015-10-22' - stats: - - metrics: - received: 0 - - date: '2015-10-23' - stats: - - metrics: - received: 0 - - date: '2015-10-24' - stats: - - metrics: - received: 0 - - date: '2015-10-25' - stats: - - metrics: - received: 0 - - date: '2015-10-26' - stats: - - metrics: - received: 0 - - date: '2015-10-27' - stats: - - metrics: - received: 0 - - date: '2015-10-28' - stats: - - metrics: - received: 0 - - date: '2015-10-29' - stats: - - metrics: - received: 0 - - date: '2015-10-30' - stats: - - metrics: - received: 0 - - date: '2015-10-31' - stats: - - metrics: - received: 0 - - date: '2015-11-01' - stats: - - metrics: - received: 0 - - date: '2015-11-02' - stats: - - metrics: - received: 0 - - date: '2015-11-03' - stats: - - metrics: - received: 0 - - date: '2015-11-04' - stats: - - metrics: - received: 0 - - date: '2015-11-05' - stats: - - metrics: - received: 0 - - date: '2015-11-06' - stats: - - metrics: - received: 0 - - date: '2015-11-07' - stats: - - metrics: - received: 0 - - date: '2015-11-08' - stats: - - metrics: - received: 0 - - date: '2015-11-09' - stats: - - metrics: - received: 0 - - date: '2015-11-10' - stats: - - metrics: - received: 0 - security: - - Authorization: [] - /subusers/stats/sums: - parameters: [] - get: - tags: - - Stats - Subuser Stats - summary: ' Retrieve the totals for each email statistic metric for all subusers.' - description: |- - **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** - - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - operationId: GET_subusers-stats-sums - consumes: - - application/json - produces: - - application/json - parameters: - - name: sort_by_direction - in: query - description: 'The direction you want to sort. ' - required: false - type: string - default: desc - enum: - - desc - - asc - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - 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 - type: string - - name: limit - in: query - description: Limits the number of results returned per page. - required: false - type: integer - default: 5 - - name: offset - in: query - description: The point in the list to begin retrieving results from. - required: false - 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 - type: string - - name: sort_by_metric - in: query - description: The metric that you want to sort by. Must be a single metric. - required: false - type: string - default: delivered - responses: - '200': - description: '' - schema: - $ref: '#/definitions/category_stats' - examples: - application/json: - date: '2015-10-11' - stats: [] - security: - - Authorization: [] - /subusers/stats: - parameters: [] - get: - tags: - - Stats - Subuser Stats - summary: Retrieve email statistics for your subusers. - 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. - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - operationId: GET_subusers-stats - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: Limits the number of results returned per page. - required: false - type: integer - - name: offset - in: query - description: The point in the list to begin retrieving results from. - required: false - type: integer - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - - 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 - type: string - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - type: string - - name: end_date - in: query - description: The end date of the statistics to retrieve. Defaults to today. - required: false - type: string - responses: - '200': - description: '' - schema: - $ref: '#/definitions/stats' - examples: - application/json: - - 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 - security: - - Authorization: [] - /api_keys: - parameters: [] - post: - summary: Create API keys - description: |- - **This enpoint allows you to create a new random API Key for the user.** - - A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. - - There is a limit of 100 API Keys on your account. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. - operationId: create-api-keys - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The name you will use to describe this API Key. - scopes: - type: array - description: The individual permissions that you are giving to this API Key. - items: - type: string - required: - - name - example: - name: My API Key - scopes: - - mail.send - - alerts.create - - alerts.read - responses: - '201': - description: '' - schema: - type: object - properties: - api_key: - type: string - api_key_id: - type: string - name: - type: string - scopes: - type: array - items: - type: string - examples: - application/json: - api_key: SG.xxxxxxxx.yyyyyyyy - api_key_id: xxxxxxxx - name: My API Key - scopes: - - mail.send - - alerts.create - - alerts.read - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: name - message: missing required argument - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: Cannot create more than 100 API Keys - security: - - Authorization: [] - get: - summary: Retrieve all API Keys belonging to the authenticated user - description: |- - **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - operationId: GET_api_keys - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - items: - $ref: '#/definitions/api_key_name_id' - examples: - application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - /categories/stats: - parameters: [] - get: - tags: - - Stats - Category Stats - summary: Retrieve Email Statistics for Categories - description: |- - **This endpoint allows you to retrieve all of your email statistics for each of your categories.** - - If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - - Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - operationId: GET_categories-stats - consumes: - - application/json - produces: - - application/json - parameters: - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD - required: true - 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 - type: string - - name: categories - in: query - description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. - required: true - type: string - - name: limit - in: query - description: The number of results to include. - required: false - type: integer - default: 500 - maximum: 500 - - name: offset - in: query - description: The number of results to skip. - required: false - type: integer - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/category_stats' - examples: - application/json: - - date: '2015-10-01' - stats: - - type: category - name: docs - 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 - - type: category - name: mattscategory - 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-11-01' - stats: - - type: category - name: docs - 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 - - type: category - name: mattscategory - 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 - security: - - Authorization: [] - /stats: - parameters: [] - get: - tags: - - Stats - Global Stats - summary: Retrieve global email statistics - description: |- - **This endpoint allows you to retrieve all of your global email statistics between a given date range.** - - Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. - operationId: GET_stats - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: The number of results to return. - required: false - type: integer - - name: offset - in: query - description: The point in the list to begin retrieving results. - required: false - type: integer - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - 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 - type: string - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - date: - type: string - description: The date the stats were gathered. - stats: - type: array - description: The individual email activity stats. - 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 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. - required: - - date - - stats - examples: - application/json: - - date: '2015-11-03' - 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 - - date: '2015-11-04' - 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 - - date: '2015-11-05' - 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 - - date: '2015-11-06' - 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 - - date: '2015-11-07' - 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 - - date: '2015-11-08' - 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 - - date: '2015-11-09' - 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 - security: - - Authorization: [] - /categories/stats/sums: - parameters: [] - get: - tags: - - Stats - Category Stats - summary: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' - description: |- - **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** - - If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - - Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - operationId: GET_categories-stats-sums - consumes: - - application/json - produces: - - application/json - parameters: - - name: sort_by_metric - in: query - description: The metric that you want to sort by. Must be a single metric. - required: false - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - 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 - type: string - - name: limit - in: query - description: Limits the number of results returned. - required: false - type: integer - default: 5 - - name: offset - in: query - description: The point in the list to begin retrieving results. - required: false - type: integer - default: 0 - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - responses: - '200': - description: '' - schema: - type: object - properties: - '': - $ref: '#/definitions/category_stats' - examples: - application/json: - date: '2015-01-01' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 20 - deferred: 0 - delivered: 20 - invalid_emails: 0 - opens: 20 - processed: 0 - requests: 20 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 20 - unique_opens: 20 - unsubscribe_drops: 0 - unsubscribes: 20 - name: cat1 - type: category - - metrics: - blocks: 1 - bounce_drops: 0 - bounces: 0 - clicks: 19 - deferred: 0 - delivered: 19 - invalid_emails: 0 - opens: 19 - processed: 0 - requests: 20 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 19 - unique_opens: 19 - unsubscribe_drops: 0 - unsubscribes: 19 - name: cat2 - type: category - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 5 - deferred: 0 - delivered: 5 - invalid_emails: 0 - opens: 5 - processed: 0 - requests: 5 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 5 - unique_opens: 5 - unsubscribe_drops: 0 - unsubscribes: 5 - name: cat3 - type: category - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 6 - deferred: 0 - delivered: 5 - invalid_emails: 0 - opens: 6 - processed: 0 - requests: 5 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 5 - unique_opens: 5 - unsubscribe_drops: 0 - unsubscribes: 6 - name: cat4 - type: category - - metrics: - blocks: 10 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 10 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: cat5 - type: category - security: - - Authorization: [] - /tracking_settings/open: - parameters: [] - get: - summary: Get Open Tracking Settings - description: |- - **This endpoint allows you to retrieve your current settings for open tracking.** - - Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: GET_tracking_settings-open - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if open tracking is enabled. - required: - - enabled - examples: - application/json: - enabled: true - security: - - Authorization: [] - patch: - summary: Update Open Tracking Settings - description: |- - **This endpoint allows you to update your current settings for open tracking.** - - Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: PATCH_tracking_settings-open - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: The new status that you want to set for open tracking. - example: - enabled: true - responses: - '200': - description: '' - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if open tracking is enabled. - required: - - enabled - examples: - application/json: - enabled: true - security: - - Authorization: [] - /tracking_settings/subscription: - parameters: [] - get: - summary: Retrieve Subscription Tracking Settings - description: |- - **This endpoint allows you to retrieve your current settings for subscription tracking.** - - Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: GET_tracking_settings-subscription - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/subscription_tracking_settings' - examples: - application/json: - enabled: true - html_content: | -

Something something unsubscribe <% %> something something

- landing: | -

subscribehere

- plain_content: Something something unsubscribe <% %> something something - replace: thetag - url: '' - security: - - Authorization: [] - patch: - summary: Update Subscription Tracking Settings - description: |- - **This endpoint allows you to update your current settings for subscription tracking.** - - Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: PATCH_tracking_settings-subscription - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/subscription_tracking_settings' - example: - enabled: true - landing: landing page html - url: url - replace: replacement tag - html_content: html content - plain_content: text content - responses: - '200': - description: '' - schema: - $ref: '#/definitions/subscription_tracking_settings' - examples: - application/json: - enabled: true - landing: landing page html - url: url - replace: replacement tag - html_content: html content - plain_content: text content - security: - - Authorization: [] - '/ips/pools/{pool_name}/ips': - parameters: - - name: pool_name - in: path - description: The name of the IP pool that you want to add an IP address to. - required: true - type: string - post: - summary: Add an IP address to a pool - description: |- - **This endpoint allows you to add an IP address to an IP pool.** - - You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - operationId: POST_ips-pools-pool_name-ips - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - ip: - type: string - description: The IP address that you want to add to an IP pool. - example: - ip: 0.0.0.0 - responses: - '201': - description: '' - schema: - type: object - properties: - ip: - type: string - description: The IP address. - pools: - type: array - description: The list of IP pools that this IP address has been added to. - items: - type: string - start_date: - type: integer - description: A unix timestamp indicating when the warmup process began for the IP address. - warmup: - type: boolean - description: Indicates if the IP address is in warmup. - required: - - ip - - pools - - start_date - - warmup - examples: - application/json: - ip: 000.00.00.0 - pools: - - test1 - start_date: 1409616000 - warmup: true - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The error returned. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the IP address could not be added to the IP Pool. - examples: - application/json: - errors: - - field: null - message: resource not found - security: - - Authorization: [] - '/ips/{ip_address}': - parameters: - - name: ip_address - in: path - description: The IP address you are retrieving the IP pools for. - required: true - type: string - get: - summary: Retrieve all IP pools an IP address belongs to - description: |- - **This endpoint allows you to see which IP pools a particular IP address has been added to.** - - The same IP address can be added to multiple IP pools. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - operationId: GET_ips-ip_address - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - ip: - type: string - description: The IP address. - subusers: - type: array - description: The subusers that can send email using this IP address. - items: - type: string - rdns: - type: string - description: The reverse DNS record for this IP address. - pools: - type: array - description: The list of IP pools that this IP address belongs to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: - - integer - - 'null' - description: The date that the IP address was entered into warmup. - whitelabeled: - type: boolean - description: Indicates if this IP address has been whitelabeled. - required: - - ip - - subusers - - rdns - - pools - - warmup - - start_date - - whitelabeled - examples: - application/json: - ip: 000.00.00.0 - subusers: - - subuser1 - - subuser2 - rdns: o1.em.example.com - pools: - - test1 - warmup: false - start_date: null - whitelabeled: true - security: - - Authorization: [] - /user/webhooks/event/settings: - parameters: [] - get: - tags: - - Webhooks - summary: Retrieve Event Webhook settings - description: |- - **This endpoint allows you to retrieve your current event webhook settings.** - - If an event type is marked as `true`, then the event webhook will include information about that event. - - SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - - Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - operationId: GET_user-webhooks-event-settings - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/event_webhook_settings' - examples: - application/json: - enabled: true - url: url - group_resubscribe: true - delivered: true - group_unsubscribe: true - spam_report: true - bounce: true - deferred: true - unsubscribe: true - processed: true - open: true - click: true - dropped: true - security: - - Authorization: [] - patch: - tags: - - Webhooks - summary: Update Event Notification Settings - description: |- - **This endpoint allows you to update your current event webhook settings.** - - If an event type is marked as `true`, then the event webhook will include information about that event. - - SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - - Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - operationId: PATCH_user-webhooks-event-settings - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/event_webhook_settings' - example: - enabled: true - url: url - group_resubscribe: true - delivered: true - group_unsubscribe: true - spam_report: true - bounce: true - deferred: true - unsubscribe: true - processed: true - open: true - click: true - dropped: true - responses: - '200': - description: '' - schema: - $ref: '#/definitions/event_webhook_settings' - examples: - application/json: - enabled: true - url: url - group_resubscribe: true - delivered: true - group_unsubscribe: true - spam_report: true - bounce: true - deferred: true - unsubscribe: true - processed: true - open: true - click: true - dropped: true - security: - - Authorization: [] - '/suppression/blocks/{email}': - parameters: - - name: email - in: path - description: The blocked email address that you want to delete. - required: true - type: string - delete: - tags: - - Blocks API - summary: Delete a specific block - description: |- - **This endpoint allows you to delete a specific email address from your blocks list.** - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: DELETE_suppression-blocks-email - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - properties: {} - get: - tags: - - Blocks API - summary: Retrieve a specific block - description: |- - **This endpoint allows you to retrieve a specific email address from your blocks list.** - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: GET_suppression-blocks-email - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the block was created. - email: - type: string - description: The email address of the recipient that was blocked. - reason: - type: string - description: The reason why the email was blocked. - status: - type: string - description: The status of the block. - required: - - created - - email - - reason - examples: - application/json: - - created: 1443651154 - email: user1@example.com - reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' - status: 4.0.0 - security: - - Authorization: [] - '/suppression/invalid_emails/{email}': - parameters: - - name: email - in: path - description: The invalid email address that you want to remove. - required: true - type: string - delete: - summary: Delete a specific invalid email - description: |- - **This endpoint allows you to remove a specific email address from the invalid email address list.** - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: DELETE_suppression-invalid_emails-email - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - properties: {} - get: - summary: Retrieve a specific invalid email - description: |- - **This endpoint allows you to retrieve a specific invalid email addresses.** - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: GET_suppression-invalid_emails-email - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the invalid emails list. - email: - type: string - description: The email address that was marked as invalid. - reason: - type: string - description: A reason explaining why the email address was marked as invalid. - required: - - created - - email - - reason - examples: - application/json: - - created: 1454433146 - email: test1@example.com - reason: Mail domain mentioned in email address is unknown - '/suppression/spam_report/{email}': - parameters: - - name: email - in: path - description: The email address for the spam report that you want to delete. - required: true - type: string - delete: - summary: Delete a specific spam report - description: |- - **This endpoint allows you to delete a specific spam report.** - - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: DELETE_suppression-spam_report-email - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - get: - summary: Retrieve a specific spam report - description: |- - **This endpoint allows you to retrieve a specific spam report.** - - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: GET_suppression-spam_report-email - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp that indicates when the recipient marked your message as spam. - email: - type: string - description: The email address of the recipient that marked your message as spam. - ip: - type: string - description: The IP address that the message was sent from. - required: - - created - - email - - ip - examples: - application/json: - - created: 1454433146 - email: test1@example.com - ip: 10.89.32.5 - security: - - Authorization: [] - '/access_settings/whitelist/{rule_id}': - parameters: - - name: rule_id - in: path - description: The ID of the whitelisted IP address that you want to retrieve. - required: true - type: string - get: - summary: Retrieve a specific whitelisted IP - description: |- - **This endpoint allows you to retreive a specific IP address that has been whitelisted.** - - You must include the ID for the specific IP address you want to retrieve in your call. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: GET_access_settings-whitelist-rule_id - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - id: - type: integer - description: The ID of the IP address. - ip: - type: string - description: The IP address. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IP address was last updated. - required: - - id - - ip - - created_at - - updated_at - examples: - application/json: - id: 1 - ip: 192.168.1.1 - created_at: 1441824715 - updated_at: 1441824715 - security: - - Authorization: [] - delete: - summary: Remove a specific IP from the whitelist - description: |- - **This endpoint allows you to remove a specific IP address from your IP whitelist.** - - When removing a specific IP address from your whitelist, you must include the ID in your call. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: DELETE_access_settings-whitelist-rule_id - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - /access_settings/activity: - parameters: [] - get: - summary: Retrieve all recent access attempts - description: |- - **This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.** - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: GET_access_settings-activity - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: Limits the number of IPs to return. - type: integer - default: 20 - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - description: An array containing the IPs that recently attempted to access your account. - items: - type: object - properties: - allowed: - type: boolean - description: Indicates if the IP address was granted access to the account. - auth_method: - type: string - description: The authentication method used when attempting access. - first_at: - type: integer - description: A Unix timestamp indicating when the first access attempt was made. - ip: - type: string - description: The IP addressed used during the access attempt. - last_at: - type: integer - description: A Unix timestamp indicating when the most recent access attempt was made - location: - type: string - description: The geographic location from which the access attempt originated. - required: - - allowed - - auth_method - - first_at - - ip - - last_at - - location - required: - - result - examples: - application/json: - result: - - allowed: false - auth_method: basic - first_at: 1444087966 - ip: 1.1.1.1 - last_at: 1444406672 - location: Australia - - allowed: false - auth_method: basic - first_at: 1444087505 - ip: 1.2.3.48 - last_at: 1444087505 - location: 'Mukilteo, Washington' - security: - - Authorization: [] - /access_settings/whitelist: - parameters: [] - post: - summary: Add one or more IPs to the whitelist - description: |- - **This endpoint allows you to add one or more IP addresses to your IP whitelist.** - - When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: POST_access_settings-whitelist - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - ips: - type: array - description: An array containing the IP(s) you want to whitelist. - items: - type: object - properties: - ip: - type: string - description: An IP address that you want to whitelist. - required: - - ip - required: - - ips - example: - ips: - - ip: 192.168.1.1 - - ip: 192.*.*.* - - ip: 192.168.1.3/32 - responses: - '201': - description: '' - schema: - type: object - properties: - result: - type: array - description: An array listing all of your whitelisted IPs. - items: - type: object - properties: - id: - type: integer - description: The ID of the whitelisted IP. - ip: - type: string - description: The whitelisted IP. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IPs whitelisting status was most recently updated. - required: - - id - - ip - - created_at - - updated_at - required: - - result - examples: - application/json: - result: - - id: 1 - ip: 192.168.1.1/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 2 - ip: 192.0.0.0/8 - created_at: 1441824715 - updated_at: 1441824715 - - id: 3 - ip: 192.168.1.3/32 - created_at: 1441824715 - updated_at: 1441824715 - security: - - Authorization: [] - get: - summary: Retrieve a list of currently whitelisted IPs - description: |- - **This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.** - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: GET_access_settings-whitelist - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - description: An array listing all of your whitelisted IPs. - items: - type: object - properties: - id: - type: integer - description: The ID of the whitelisted IP. - ip: - type: string - description: The whitelisted IP. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IPs whitelisting status was most recently updated. - required: - - id - - ip - - created_at - - updated_at - required: - - result - examples: - application/json: - result: - - id: 1 - ip: 192.168.1.1/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 2 - ip: 192.168.1.2/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 3 - ip: 192.168.1.3/32 - created_at: 1441824715 - updated_at: 1441824715 - security: - - Authorization: [] - delete: - summary: Remove one or more IPs from the whitelist - description: |- - **This endpoint allows you to remove one or more IPs from your IP whitelist.** - - You can remove one IP at a time, or you can remove multiple IP addresses. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: DELETE_access_settings-whitelist - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: object - properties: - ids: - type: array - description: An array of the IDs of the IP address that you want to remove from your whitelist. - items: - type: integer - example: - ids: - - 1 - - 2 - - 3 - responses: - '204': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - /subusers/stats/monthly: - parameters: [] - get: - tags: - - Stats - Subuser Stats - summary: Retrieve monthly stats for all subusers - description: |- - **This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - 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`. - - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - operationId: GET_subusers-stats-monthly - consumes: - - application/json - produces: - - application/json - parameters: - - name: date - in: query - description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD - required: true - type: string - - name: subuser - in: query - description: A substring search of your subusers. - required: false - 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 - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: limit - in: query - description: Optional field to limit the number of results returned. - required: false - type: integer - default: 5 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - required: false - type: integer - default: 0 - responses: - '200': - description: '' - schema: - $ref: '#/definitions/subuser_stats' - examples: - application/json: - 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 - security: - - Authorization: [] - '/ips/pools/{pool_name}/ips/{ip}': - parameters: - - name: pool_name - in: path - description: The name of the IP pool that you are removing the IP address from. - required: true - type: string - - name: ip - in: path - description: The IP address that you are removing. - required: true - type: string - delete: - summary: Remove an IP address from a pool. - description: |- - **This endpoint allows you to remove an IP address from an IP pool.** - - The same IP address can be added to multiple IP pools. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - operationId: DELETE_ips-pools-pool_name-ips-ip - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - '404': - description: '' - schema: - type: object - properties: - error: - type: string - description: An error explaining why the IP address could not be removed from the IP pool. - examples: - application/json: - error: Unable to locate specified IPs Pool - security: - - Authorization: [] - /user/settings/enforced_tls: - parameters: [] - get: - summary: Retrieve current Enforced TLS settings. - description: |- - **This endpoint allows you to retrieve your current Enforced TLS settings.** - - The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. - - **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. - operationId: GET_user-settings-enforced_tls - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - require_tls: - type: boolean - description: Indicates if the recipient is required to support TLS. - require_valid_cert: - type: boolean - description: Indicates if the recipient is required to have a valid certificate. - required: - - require_tls - - require_valid_cert - examples: - application/json: - require_tls: false - require_valid_cert: false - security: - - Authorization: [] - patch: - summary: Update Enforced TLS settings - description: |- - **This endpoint allows you to update your current Enforced TLS settings.** - - The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. - - **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. - operationId: PATCH_user-settings-enforced_tls - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - require_tls: - type: boolean - description: 'Indicates if you want to require your recipients to support TLS. ' - require_valid_cert: - type: boolean - description: Indicates if you want to require your recipients to have a valid certificate. - example: - require_tls: true - require_valid_cert: false - responses: - '200': - description: '' - schema: - type: object - properties: - require_tls: - type: boolean - description: Indicates if your recipients are required to support TLS. - require_valid_cert: - type: boolean - description: Indicates if your recipients are required to have a valid certificate. - required: - - require_tls - - require_valid_cert - examples: - application/json: - require_tls: true - require_valid_cert: false - security: - - Authorization: [] - '/subusers/{subuser_name}/stats/monthly': - parameters: - - name: subuser_name - in: path - required: true - type: string - get: - summary: Retrieve the monthly email statistics for a single subuser - description: |- - **This endpoint allows you to retrive the monthly email statistics for a specific subuser.** - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - 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`. - - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - operationId: GET_subusers-subuser_name-stats-monthly - consumes: - - application/json - produces: - - application/json - parameters: - - name: date - in: query - description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD - required: true - 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 - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: limit - in: query - description: Optional field to limit the number of results returned. - required: false - type: number - default: 5 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - required: false - type: integer - default: 0 - responses: - '200': - description: '' - schema: - $ref: '#/definitions/subuser_stats' - examples: - application/json: - 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 - security: - - Authorization: [] - /user/credits: - parameters: [] - get: - tags: - - Users API - summary: Retrieve your credit balance - description: |- - **This endpoint allows you to retrieve the current credit balance for your account.** - - Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html). - operationId: GET_user-credits - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - remain: - type: integer - description: The remaining number of credits available on your account. - total: - type: integer - description: The total number of credits assigned to your account. - overage: - type: integer - description: The number of overdrawn credits for your account. - used: - type: integer - description: The number of credits that you have used. - last_reset: - type: string - description: The date that your credit balance was last reset. - next_reset: - type: string - description: The next date that your credit balance will be reset. - reset_frequency: - type: string - description: The frequency at which your credit balance will be reset. - required: - - remain - - total - - overage - - used - - last_reset - - next_reset - - reset_frequency - examples: - application/json: - remain: 200 - total: 200 - overage: 0 - used: 0 - last_reset: '2013-01-01' - next_reset: '2013-02-01' - reset_frequency: monthly - security: - - Authorization: [] - /user/password: - parameters: [] - put: - tags: - - Users API - summary: Update your password - description: |- - **This endpoint allows you to update your password.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: - - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: PUT_user-password - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: object - properties: - new_password: - type: string - description: The new password you would like to use for your account. - old_password: - type: string - description: The old password for your account. - required: - - new_password - - old_password - example: - new_password: new_password - old_password: old_password - responses: - '200': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - '/subusers/{subuser_name}/monitor': - parameters: - - name: subuser_name - in: path - description: The name of the subuser for which to retrieve monitor settings. - required: true - type: string - get: - summary: Retrieve monitor settings for a subuser - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - operationId: GET_subusers-subuser_name-monitor - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/monitor' - examples: - application/json: - email: example@example.com - frequency: 500 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: No monitor settings for this user - security: - - Authorization: [] - put: - summary: Update Monitor Settings for a subuser - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - operationId: PUT_subusers-subuser_name-monitor - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/monitor' - example: - email: example@example.com - frequency: 500 - responses: - '200': - description: '' - schema: - $ref: '#/definitions/monitor' - examples: - application/json: - email: example@example.com - frequency: 500 - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: email - message: Email is required - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - post: - summary: Create monitor settings - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - operationId: POST_subusers-subuser_name-monitor - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/monitor' - example: - email: example@example.com - frequency: 50000 - responses: - '200': - description: '' - schema: - $ref: '#/definitions/monitor' - examples: - application/json: - email: example@example.com - frequency: 50000 - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: User already has a monitor - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - delete: - summary: Delete monitor settings - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - operationId: DELETE_subusers-subuser_name-monitor - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: No monitor settings for this user - /mailbox_providers/stats: - parameters: [] - get: - summary: Retrieve email statistics by mailbox provider. - description: |- - **This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.** - - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - operationId: GET_mailbox_providers-stats - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: The number of results to include on each page. - required: false - type: integer - - name: offset - in: query - description: The number of results to exclude. - required: false - type: integer - - name: aggregated_by - in: query - description: 'How to group the stats. Must be either "day", "wee", or "month".' - required: false - type: string - enum: - - day - - week - - month - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - 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 - type: string - - name: mailbox_providers - in: query - description: The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times. - required: false - type: string - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/advanced_stats_mailbox_provider' + $ref: '#/definitions/advanced_stats_mailbox_provider' examples: application/json: - date: '2015-10-11' @@ -6853,43 +3677,342 @@ paths: unique_opens: 0 security: - Authorization: [] - '/api_keys/{api_key_id}': - parameters: - - name: api_key_id - in: path - required: true - type: string + '/api_keys/{api_key_id}': + parameters: + - name: api_key_id + in: path + required: true + type: string + delete: + summary: Delete API keys + description: |- + **This endpoint allows you to revoke an existing API Key** + + Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are deleting.| + operationId: DELETE_api_keys-api_key_id + consumes: [] + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: 'null' + examples: + application/json: null + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: unable to find API Key + security: + - Authorization: [] + put: + summary: Update the name & scopes of an API Key + description: | + **This endpoint allows you to update the name and scopes of a given API key.** + + A JSON request body with a "name" property is required. + Most provide the list of all the scopes an api key should have. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + operationId: PUT_api_keys-api_key_id + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + scopes: + type: array + items: + type: string + example: + name: A New Hope + scopes: + - user.profile.read + - user.profile.update + responses: + '200': + description: '' + schema: + $ref: '#/definitions/api_key_name_id_scopes' + examples: + application/json: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + scopes: + - user.profile.read + - user.profile.update + '400': + description: Unexpected error in API call. See HTTP response body for details. + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: expected JSON request body with 'name' property + '401': + description: '' + schema: + type: object + '404': + description: Unexpected error in API call. See HTTP response body for details. + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: unable to find API Key to update + security: + - Authorization: [] + get: + summary: Retrieve an existing API Key + description: |- + **This endpoint allows you to retrieve a single api key.** + + If the API Key ID does not exist an HTTP 404 will be returned. + operationId: GET_api_keys-api_key_id + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/api_key_name_id_scopes' + examples: + application/json: + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object + examples: + application/json: + errors: + - field: null + message: unable to find API Key + security: + - Authorization: [] + patch: + summary: Update API keys + description: |- + **This endpoint allows you to update the name of an existing API Key.** + + A JSON request body with a "name" property is required. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are updating.| + operationId: PATCH_api_keys-api_key_id + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The new name of the API Key. + example: + name: A New Hope + responses: + '200': + description: '' + schema: + $ref: '#/definitions/api_key_name_id' + examples: + application/json: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + '/user/scheduled_sends/{batch_id}': + parameters: + - name: batch_id + in: path + required: true + type: string + get: + summary: Retrieve scheduled send + description: |- + **This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: GET_user-scheduled_sends-batch_id + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: array + title: Retrieve scheduled send response + items: + $ref: '#/definitions/user_scheduled_send_status' + examples: + application/json: + - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + status: cancel + - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg + status: pause + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + patch: + summary: Update user scheduled send information + description: |- + **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: PATCH_user-scheduled_sends-batch_id + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + status: + type: string + description: The status you would like the scheduled send to have. + enum: + - cancel + - pause + required: + - status + example: + status: pause + responses: + '204': + description: '' + schema: + type: 'null' + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: status + message: status must be either cancel or pause + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"" : "batch id not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: batch id not found + security: + - Authorization: [] delete: - summary: Delete API keys + summary: Delete a cancellation or pause of a scheduled send description: |- - **This endpoint allows you to revoke an existing API Key** - - Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters + **This endpoint allows you to delete the cancellation/pause of a scheduled send.** - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are deleting.| - operationId: DELETE_api_keys-api_key_id - consumes: - - application/json + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: DELETE_user-scheduled_sends-batch_id + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '204': description: '' schema: type: 'null' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: - application/json: null + application/json: + errors: + - field: null + message: authorization required '404': description: '' schema: @@ -6898,190 +4021,248 @@ paths: application/json: errors: - field: null - message: unable to find API Key + message: batch id not found security: - Authorization: [] - put: - summary: Update the name & scopes of an API Key - description: | - **This endpoint allows you to update the name and scopes of a given API key.** - - A JSON request body with a "name" property is required. - Most provide the list of all the scopes an api key should have. + /contactdb/reserved_fields: + parameters: [] + get: + summary: Retrieve reserved fields + description: |- + **This endpoint allows you to list all fields that are reserved and can't be used for custom field names.** - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - operationId: PUT_api_keys-api_key_id - consumes: - - application/json + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: GET_contactdb-reserved_fields + consumes: [] produces: - application/json - parameters: - - name: body - in: body + parameters: [] + responses: + '200': + description: '' schema: + title: List fields that are reserved and can't be used for custom field names. response type: object properties: - name: - type: string - scopes: + reserved_fields: type: array + description: The reserved fields that are already set up within custom fields. items: - type: string - example: - name: A New Hope - scopes: - - user.profile.read - - user.profile.update - responses: - '200': - description: '' - schema: - $ref: '#/definitions/api_key_name_id_scopes' + $ref: '#/definitions/contactdb_custom_field' + required: + - reserved_fields examples: application/json: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - scopes: - - user.profile.read - - user.profile.update - '400': - description: Unexpected error in API call. See HTTP response body for details. + reserved_fields: + - name: first_name + type: text + - name: last_name + type: text + - name: email + type: text + - name: created_at + type: date + - name: updated_at + type: date + - name: last_emailed + type: date + - name: last_clicked + type: date + - name: last_opened + type: date + - name: my_custom_field + type: text + '401': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: expected JSON request body with 'name' property - '401': + message: authorization required + security: + - Authorization: [] + '/campaigns/{campaign_id}/schedules': + parameters: + - name: campaign_id + in: path + required: true + type: integer + delete: + summary: Unschedule a Scheduled Campaign + description: |- + **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** + + A successful unschedule will return a 204. + If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: DELETE_campaigns-campaign_id-schedules + consumes: [] + produces: + - application/json + parameters: [] + responses: + '204': description: '' schema: - type: object + type: 'null' + '403': + description: |- + "": "This campaign is already In Progress." + "": "This campaign is already Sent." + "": "This campaign is already Paused." + "": "This campaign is already Canceled." + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: This campaign is already In Progress. + - field: null + message: This campaign is already Sent. + - field: null + message: This campaign is already Paused. + - field: null + message: This campaign is already Canceled. '404': - description: Unexpected error in API call. See HTTP response body for details. + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: unable to find API Key to update + message: not found security: - Authorization: [] - get: - summary: Retrieve an existing API Key + post: + summary: Schedule a Campaign description: |- - **This endpoint allows you to retrieve a single api key.** + **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** - If the API Key ID does not exist an HTTP 404 will be returned. - operationId: GET_api_keys-api_key_id + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns-campaign_id-schedules consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + title: Schedule a Campaign request + type: object + properties: + send_at: + type: integer + description: The unix timestamp for the date and time you would like your campaign to be sent out. + required: + - send_at + example: + send_at: 1489771528 responses: - '200': + '201': description: '' schema: + title: Schedule a Campaign response type: object properties: - result: - type: array - items: - $ref: '#/definitions/api_key_name_id_scopes' + id: + type: integer + description: The campaign ID. + send_at: + type: integer + description: The date time you scheduled your campaign to be sent. + status: + type: string + description: The status of your campaign. + enum: + - Scheduled + required: + - id + - send_at + - status examples: application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id - '401': - description: '' + id: 1234 + send_at: 1489771528 + status: Scheduled + '400': + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "send_at": "Please choose a future time for sending your campaign." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "The JSON you have submitted cannot be parsed." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: + - field: subject + message: subject can't be blank + - field: sender_id + message: sender_id can't be blank + - field: plain_content + message: 'plain_content can''t be blank, please provide plain text or html content' + - field: list_id + message: You must select at least 1 segment or 1 list to send to. + - field: unsubscribe_tag + message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' + - field: suppression_group_id + message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - field: null - message: authorization required - '404': - description: Unexpected error in API call. See HTTP response body for details. + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + '401': + description: '' schema: - type: object + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: unable to find API Key - security: - - Authorization: [] - patch: - summary: Update API keys - description: |- - **This endpoint allows you to update the name of an existing API Key.** - - A JSON request body with a "name" property is required. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters - - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| - operationId: PATCH_api_keys-api_key_id - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The new name of the API Key. - example: - name: A New Hope - responses: - '200': - description: '' + message: authorization required + '403': + description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' schema: - $ref: '#/definitions/api_key_name_id' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - '401': - description: '' + errors: + - field: null + message: You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH. + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required + message: not found security: - Authorization: [] - /user/profile: - parameters: [] get: - tags: - - Users API - summary: Get a user's profile + summary: View Scheduled Time of a Campaign description: |- - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + **This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.** - For more information about your user profile: + For more information: - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: GET_user-profile - consumes: - - application/json + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: GET_campaigns-campaign_id-schedules + consumes: [] produces: - application/json parameters: [] @@ -7089,87 +4270,37 @@ paths: '200': description: '' schema: - title: GET User Profile response + title: View Scheduled Time of a Campaign response type: object properties: - address: - type: string - description: The user's address. - address2: - type: string - description: The second line of the user's address. - city: - type: string - description: The user's city. - company: - type: string - description: The name of the user's company. - country: - type: string - description: The user's country. - first_name: - type: string - description: The user's first name. - last_name: - type: string - description: The user's last name. - phone: - type: string - description: The user's phone number. - state: - type: string - description: The user's state. - website: - type: string - description: The user's website URL. - zip: - type: string - description: The user's zip code. + send_at: + type: integer + format: int64 required: - - address - - city - - company - - country - - first_name - - last_name - - phone - - state - - website - - zip + - send_at examples: application/json: - address: 814 West Chapman Avenue - address2: '' - city: Orange - company: SendGrid - country: US - first_name: Test - last_name: User - phone: 555-555-5555 - state: CA - website: 'http://www.sendgrid.com' - zip: '92868' - '401': - description: '' + send_at: 1490778528 + '404': + description: '"": "not found"' schema: - type: object + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: not found security: - Authorization: [] patch: - tags: - - Users API - summary: Update a user's profile + summary: Update a Scheduled Campaign description: |- - **This endpoint allows you to update your current profile details.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: + **This endpoint allows to you change the scheduled time and date for a campaign to be sent.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + For more information: - It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. - operationId: PATCH_user-profile + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: PATCH_campaigns-campaign_id-schedules consumes: - application/json produces: @@ -7178,94 +4309,131 @@ paths: - name: body in: body schema: - $ref: '#/definitions/user_profile' + title: Update a Scheduled Campaign request + type: object + properties: + send_at: + type: integer + format: int64 + required: + - send_at example: - first_name: Example - last_name: User - city: Orange - - name: on-behalf-of - in: header - description: 'You can enter a subuser name as the value for this header, in order to update the subuser''s profile.' - type: string + send_at: 1489451436 responses: '200': description: '' schema: - $ref: '#/definitions/user_profile' + title: Update a Scheduled Campaign response + type: object + properties: + id: + type: integer + description: The campaign ID + send_at: + type: integer + description: The unix timestamp to send the campaign. + status: + type: string + description: The status of the schedule. + required: + - id + - send_at + - status + '400': + description: |- + "": "The JSON you have submitted cannot be parsed." + "send_at": "Please choose a future time for sending your campaign." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - address: 814 West Chapman Avenue - address2: '' - city: Orange - company: SendGrid - country: US - first_name: Example - last_name: User - phone: 555-555-5555 - state: CA - website: 'http://www.sendgrid.com' - zip: '92868' - '401': - description: '' + errors: + - field: send_at + message: Please choose a future time for sending your campaign. + - field: null + message: The JSON you have submitted cannot be parsed. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing' + '403': + description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: send_at + message: You cannot update the send_at value of non-scheduled campaign. + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required + message: not found security: - Authorization: [] - '/user/scheduled_sends/{batch_id}': - parameters: - - name: batch_id - in: path - required: true - type: string + /asm/groups: + parameters: [] get: - summary: Retrieve scheduled send + tags: + - Suppression Management - Unsubscribe Groups + summary: Retrieve information about multiple suppression groups description: |- - **This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** + **This endpoint allows you to retrieve information about multiple suppression groups.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: GET_user-scheduled_sends-batch_id - consumes: - - application/json + This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID. + + Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). + + Suppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content. + operationId: GET_asm-groups + consumes: [] produces: - application/json - parameters: [] + parameters: + - name: id + in: query + description: The ID of a suppression group that you want to retrieve information for. + type: integer responses: '200': description: '' schema: type: array - title: Retrieve scheduled send response items: - $ref: '#/definitions/user_scheduled_send_status' - examples: - application/json: - - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - status: cancel - - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg - status: pause - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/suppression_group' examples: application/json: - errors: - - field: null - message: authorization required + - id: 100 + name: Newsletters + description: Our monthly newsletter. + last_email_sent_at: null + is_default: true + unsubscribes: 400 + - id: 101 + name: Alerts + description: Emails triggered by user-defined rules. + last_email_sent_at: null + is_default: false + unsubscribes: 1 security: - Authorization: [] - patch: - summary: Update user scheduled send information + post: + tags: + - Suppression Management - Unsubscribe Groups + summary: Create a new suppression group description: |- - **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** + **This endpoint allows you to create a new suppression group.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: PATCH_user-scheduled_sends-batch_id + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: POST_asm-groups consumes: - application/json produces: @@ -7276,57 +4444,173 @@ paths: schema: type: object properties: - status: + name: type: string - description: The status you would like the scheduled send to have. - enum: - - cancel - - pause + description: The name that you would like to use for your new suppression group. + maxLength: 30 + description: + type: string + description: A brief description of your new suppression group. + maxLength: 100 + is_default: + type: boolean + description: Indicates if you would like this to be your default suppression group. required: - - status + - name + - description example: - status: pause + name: Product Suggestions + description: Suggestions for products our users might like. + is_default: true responses: - '204': + '201': description: '' schema: - type: 'null' - '400': + type: object + properties: + id: + type: integer + description: The ID of the suppression group. + name: + type: string + description: The name of the suppression group. + description: + type: string + description: A brief description of the suppression group. + is_default: + type: boolean + description: Indicates if this is the default suppression group. + required: + - id + - name + - description + - is_default + examples: + application/json: + id: 103 + name: Product Suggestions + description: Suggestions for products our users might like. + is_default: false + security: + - Authorization: [] + '/contactdb/lists/{list_id}/recipients': + parameters: + - name: list_id + in: path + description: The id of the list of recipients you want to retrieve. + required: true + type: integer + get: + summary: Retrieve all recipients on a List + description: |- + **This endpoint allows you to retrieve all recipients on the list with the given ID.** + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-lists-list_id-recipients + consumes: [] + produces: + - application/json + parameters: + - name: page + in: query + description: Page index of first recipient to return (must be a positive integer) + required: false + type: integer + - name: page_size + in: query + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + required: false + type: integer + - name: list_id + in: query + description: The ID of the list whose recipients you are requesting. + required: true + type: integer + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + recipients: + type: array + items: + $ref: '#/definitions/contactdb_recipient' examples: application/json: - errors: - - field: status - message: status must be either cancel or pause - '401': - description: '' + recipients: + - created_at: 1433348344 + custom_fields: + - id: 6234 + name: age + type: number + value: null + - id: 6233 + name: country + type: text + value: null + - id: 6235 + name: fname + type: text + value: Example + - id: 6239 + name: lname + type: text + value: User + - id: 6240 + name: lname + type: text + value: null + email: example@example.com + first_name: Example + id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv== + last_clicked: 1438616117 + last_emailed: 1438613272 + last_name: User + last_opened: 1438616109 + updated_at: 1438616119 + '400': + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: authorization required + - field: list_id + message: Returned if list_id is not a valid integer + - field: page + message: Returned if page is not a valid integer + - field: page + message: Returned if page is less than 1 + - field: page_size + message: Returned if page_size is not a valid integer + - field: page_size + message: Returned if page_size is less than 1 or greater than 1000 '404': - description: '"" : "batch id not found"' + description: '"list_id" : "Returned if list_id does not exist"' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - - field: null - message: batch id not found + - field: list_id + message: Returned if list_id is invalid security: - Authorization: [] - delete: - summary: Delete a cancellation or pause of a scheduled send + post: + summary: Add Multiple Recipients to a List description: |- - **This endpoint allows you to delete the cancellation/pause of a scheduled send.** + **This endpoint allows you to add multiple recipients to a list.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: DELETE_user-scheduled_sends-batch_id + Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: POST_contactdb-lists-list_id-recipients consumes: - application/json produces: @@ -7335,12 +4619,36 @@ paths: - name: body in: body schema: - type: 'null' + type: array + items: + type: string + example: + - recipient_id1 + - recipient_id2 responses: - '204': + '201': description: '' schema: type: 'null' + '400': + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "" : "Returned if no valid recipient ids were passed" + "" : "Returned if no recipients were added" + "" : "Returned if request body is invalid JSON" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: list_id + message: list_id is invalid + - field: recipient_id + message: no valid recipients were provided + - field: null + message: no recipients were added + - field: null + message: request body is invalid JSON '401': description: '' schema: @@ -7351,265 +4659,230 @@ paths: - field: null message: authorization required '404': - description: '' + description: '"list_id": "Returned if list_id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: batch id not found + - field: list_id + message: list_id does not exist + - field: recipient_id + message: recipient_id does not exist security: - Authorization: [] - /campaigns: - parameters: [] + '/contactdb/segments/{segment_id}': + parameters: + - name: segment_id + in: path + required: true + type: string get: - tags: - - Campaigns API - summary: Retrieve all Campaigns + summary: Retrieve a segment description: |- - **This endpoint allows you to retrieve a list of all of your campaigns.** - - Returns campaigns in reverse order they were created (newest first). - - Returns an empty array if no campaigns exist. + **This endpoint allows you to retrieve a single segment with the given ID.** - For more information: + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: GET_campaigns - consumes: - - application/json + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: GET_contactdb-segments-segment_id + consumes: [] produces: - application/json parameters: - - name: limit - in: query - description: The number of results you would like to receive at a time. - type: number - default: 10 - - name: offset + - name: segment_id in: query - description: 'The index of the first campaign to return, where 0 is the first campaign.' - type: number - default: 0 + description: The ID of the segment you want to request. + required: true + type: integer responses: '200': description: '' schema: - type: object - properties: - result: - type: array - items: - $ref: '#/definitions/campaign_response' + $ref: '#/definitions/contactdb_segments' examples: application/json: - result: - - id: 986724 - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Check out our spring line!

- plain_content: Check out our spring line! - status: Draft - - id: 986723 - title: February Newsletter - subject: Final Winter Product Sale! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - winter line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Last call for winter clothes!

- plain_content: Last call for winter clothes! - status: Sent + id: 1 + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + recipient_count: 1 + '400': + description: '"segment_id" : "Returned if segment_id is not valid"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: if segment_id is not valid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: segment_id not found security: - Authorization: [] - post: - tags: - - Campaigns API - summary: Create a Campaign + delete: + summary: Delete a segment description: |- - **This endpoint allows you to create a campaign.** - - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + **This endpoint allows you to delete a segment from your recipients database.** - Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. - For more information: + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns - consumes: - - application/json + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: DELETE_contactdb-segments-segment_id + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - $ref: '#/definitions/campaign_request' - example: - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Check out our spring line!

- plain_content: Check out our spring line! + - name: delete_contacts + in: query + description: True to delete all contacts matching the segment in addition to deleting the segment + type: boolean responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/campaign_response' - examples: - application/json: - id: 986724 - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Check out our spring line!

- plain_content: Check out our spring line! - status: Draft + type: 'null' '400': description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + "segment_id" : "Returned if segment_id is not valid" + "delete_contacts" : "Returned if delete_contacts is not a valid boolean" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: title - message: title can't be blank - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: You've reached your limit of 250 campaigns. Please delete one or more and try again. + - field: segment_id + message: Returned if segment_id is not valid + - field: delete_contacts + message: Returned if delete_contacts is not a valid boolean '401': description: '' schema: - type: object + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: segment_id + message: segment_id does not exist security: - Authorization: [] - /contactdb/reserved_fields: - parameters: [] - get: - summary: Retrieve reserved fields + patch: + summary: Update a segment description: |- - **This endpoint allows you to list all fields that are reserved and can't be used for custom field names.** + **This endpoint allows you to update a segment.** + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-reserved_fields + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: PATCH_contactdb-segments-segment_id consumes: - application/json produces: - application/json - parameters: [] - responses: - '200': - description: '' + parameters: + - name: segment_id + in: query + description: The ID of the segment you are updating. + type: string + - name: body + in: body schema: - title: List fields that are reserved and can't be used for custom field names. response type: object properties: - reserved_fields: + name: + type: string + list_id: + type: number + description: The list ID you would like this segment to be built from. + conditions: type: array - description: The reserved fields that are already set up within custom fields. + description: The conditions by which this segment should be created. items: - $ref: '#/definitions/contactdb_custom_field' + $ref: '#/definitions/contactdb_segments_conditions' required: - - reserved_fields + - name + example: + name: The Millers + list_id: 5 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contactdb_segments' examples: application/json: - reserved_fields: - - name: first_name - type: text - - name: last_name - type: text - - name: email - type: text - - name: created_at - type: date - - name: updated_at - type: date - - name: last_emailed - type: date - - name: last_clicked - type: date - - name: last_opened - type: date - - name: my_custom_field - type: text + id: 5 + name: The Millers + list_id: 5 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + recipient_count: 1 + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: request body is not valid json + - message: invalid value is passed into one of the request body parameters + - segment_id: segment_id + message: segment id is not valid + - field: field + message: field and set value is not passed into the request body + - field: value + message: value and set value is not passed into the request body + - field: operator + message: operator and set value is not passed into the request body + - field: and_or + message: and_or is not set on more than one condition and less than all conditions + - field: and_or + message: and_or is set on all conditions + - field: and_or + message: and_or is set on the only condition passed + - field: and_or + message: and_or and set value is not passed into the request body + - field: list_id + message: the list_id is not valid + - field: name + message: the name is not valid '401': description: '' schema: @@ -7621,278 +4894,171 @@ paths: message: authorization required security: - Authorization: [] - /asm/groups: + /clients/stats: parameters: [] get: tags: - - Suppression Management - Unsubscribe Groups - summary: Retrieve information about multiple suppression groups + - Stats - Advanced Stats + summary: Retrieve email statistics by client type. description: |- - **This endpoint allows you to retrieve information about multiple suppression groups.** + **This endpoint allows you to retrieve your email statistics segmented by client type.** - This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID. - operationId: GET_asm-groups - consumes: - - application/json + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_clients-stats + consumes: [] produces: - application/json parameters: - - name: id + - name: start_date in: query - description: The ID of a suppression group that you want to retrieve information for. - type: integer + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + 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 + type: string + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: '200': description: '' schema: type: array items: - $ref: '#/definitions/suppression_group' - examples: - application/json: - - id: 100 - name: Newsletters - description: Our monthly newsletter. - last_email_sent_at: null - is_default: true - unsubscribes: 400 - - id: 101 - name: Alerts - description: Emails triggered by user-defined rules. - last_email_sent_at: null - is_default: false - unsubscribes: 1 - security: - - Authorization: [] - post: - tags: - - Suppression Management - Unsubscribe Groups - summary: Create a new suppression group - description: |- - **This endpoint allows you to create a new suppression group.** - - Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - - The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. - - Each user can create up to 25 different suppression groups. - operationId: POST_asm-groups - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The name that you would like to use for your new suppression group. - maxLength: 30 - description: - type: string - description: A brief description of your new suppression group. - maxLength: 100 - is_default: - type: boolean - description: Indicates if you would like this to be your default suppression group. - required: - - name - - description - example: - name: Product Suggestions - description: Suggestions for products our users might like. - is_default: true - responses: - '201': - description: '' - schema: - type: object - properties: - id: - type: integer - description: The ID of the suppression group. - name: - type: string - description: The name of the suppression group. - description: - type: string - description: A brief description of the suppression group. - is_default: - type: boolean - description: Indicates if this is the default suppression group. - required: - - id - - name - - description - - is_default + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - id: 103 - name: Product Suggestions - description: Suggestions for products our users might like. - is_default: false + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client security: - Authorization: [] - '/contactdb/lists/{list_id}/recipients': + '/contactdb/lists/{list_id}/recipients/{recipient_id}': parameters: - name: list_id in: path - description: The id of the list of recipients you want to retrieve. + description: The ID of the list that you want to add the recipient to. required: true type: integer - get: - summary: Retrieve all recipients on a List + - name: recipient_id + in: path + description: The ID of the recipient you are adding to the list. + required: true + type: string + post: + summary: Add a Single Recipient to a List description: |- - **This endpoint allows you to retrieve all recipients on the list with the given ID.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-lists-list_id-recipients - consumes: - - application/json + **This endpoint allows you to add a single recipient to a list.** + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: POST_contactdb-lists-list_id-recipients-recipient_id + consumes: [] produces: - application/json - parameters: - - name: page - in: query - description: Page index of first recipient to return (must be a positive integer) - required: false - type: integer - - name: page_size - in: query - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - required: false - type: integer - - name: list_id - in: query - description: The ID of the list whose recipients you are requesting. - required: true - type: number + parameters: [] responses: - '200': + '201': description: '' schema: - type: object - properties: - recipients: - type: array - items: - $ref: '#/definitions/contactdb_recipient' - examples: - application/json: - recipients: - - created_at: 1433348344 - custom_fields: - - id: 6234 - name: age - type: number - value: null - - id: 6233 - name: country - type: text - value: null - - id: 6235 - name: fname - type: text - value: Example - - id: 6239 - name: lname - type: text - value: User - - id: 6240 - name: lname - type: text - value: null - email: example@example.com - first_name: Example - id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv== - last_clicked: 1438616117 - last_emailed: 1438613272 - last_name: User - last_opened: 1438616109 - updated_at: 1438616119 + type: 'null' '400': description: |- - "list_id" : "Returned if list_id is not a valid integer" - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" + "list_id" : "Returned if list_id is invalid" + "recipient_id" : "Returned if recipient_id is invalid" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: list_id - message: Returned if list_id is not a valid integer - - field: page - message: Returned if page is not a valid integer - - field: page - message: Returned if page is less than 1 - - field: page_size - message: Returned if page_size is not a valid integer - - field: page_size - message: Returned if page_size is less than 1 or greater than 1000 + message: Returned if list_id is invalid + - field: recipient_id + message: Returned if recipient_id is invalid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required '404': - description: '"list_id" : "Returned if list_id does not exist"' + description: |- + "list_id" : "Returned if list_id does not exist" + "recipient_id" : "Returned if recipient_id does not exist" schema: - type: object + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: list_id - message: Returned if list_id is invalid + message: Returned if list_id does not exist + - field: recipient_id + message: Returned if recipient_id does not exist security: - Authorization: [] - post: - summary: Add Multiple Recipients to a List + delete: + summary: Delete a Single Recipient from a Single List description: |- - **This endpoint allows you to add multiple recipients to a list.** - - Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + **This endpoint allows you to delete a single recipient from a list.** The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: POST_contactdb-lists-list_id-recipients - consumes: - - application/json + operationId: DELETE_contactdb-lists-list_id-recipients-recipient_id + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - type: array - items: - type: string - example: - - recipient_id1 - - recipient_id2 + - name: list_id + in: query + description: The ID of the list you are taking this recipient away from. + required: true + type: integer + - name: recipient_id + in: query + description: The ID of the recipient to take off the list. + required: true + type: integer responses: - '201': + '204': description: '' schema: type: 'null' '400': description: |- - "list_id" : "Returned if list_id is not a valid integer" - "" : "Returned if no valid recipient ids were passed" - "" : "Returned if no recipients were added" - "" : "Returned if request body is invalid JSON" + "list_id" : "Returned if list_id is not valid" + "recipient_id" : "Returned if recipient_id is not valid" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: list_id - message: list_id is invalid + message: Returned if list_id is invalid - field: recipient_id message: no valid recipients were provided - - field: null - message: no recipients were added - - field: null - message: request body is invalid JSON '401': description: '' schema: @@ -7903,67 +5069,67 @@ paths: - field: null message: authorization required '404': - description: '"list_id": "Returned if list_id does not exist"' + description: |- + "list_id" : "Returned if list_id does not exist" + "recipient_id" : "Returned if recipient_id does not exist" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: list_id - message: list_id does not exist + message: Returned if list_id does not exist - field: recipient_id - message: recipient_id does not exist + message: Returned if recipient_id does not exist security: - Authorization: [] - '/contactdb/segments/{segment_id}': - parameters: - - name: segment_id - in: path - required: true - type: string + /contactdb/recipients: + parameters: [] get: - summary: Retrieve a segment + tags: + - Contacts API - Recipients + summary: Retrieve recipients description: |- - **This endpoint allows you to retrieve a single segment with the given ID.** + **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of + the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: GET_contactdb-segments-segment_id - consumes: - - application/json + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-recipients + consumes: [] produces: - application/json parameters: - - name: segment_id + - name: page in: query - description: The ID of the segment you want to request. - required: true - type: number + description: Page index of first recipients to return (must be a positive integer) + type: integer + - name: page_size + in: query + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + type: integer responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_segments' - examples: - application/json: - id: 1 - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - recipient_count: 1 + title: List Recipients response + type: object + properties: + recipients: + type: array + items: + type: object + required: + - recipients '400': - description: '"segment_id" : "Returned if segment_id is not valid"' + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: if segment_id is not valid + type: object '401': description: '' schema: @@ -7973,58 +5139,62 @@ paths: errors: - field: null message: authorization required - '404': - description: '"segment_id" : "Returned if segment_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: segment_id not found security: - Authorization: [] - delete: - summary: Delete a segment + patch: + tags: + - Contacts API - Recipients + summary: Update Recipient description: |- - **This endpoint allows you to delete a segment from your recipients database.** + **This endpoint allows you to update one or more recipients.** - You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. + The body of an API call to this endpoint must include an array of one or more recipient objects. - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: DELETE_contactdb-segments-segment_id + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: PATCH_contactdb-recipients consumes: - application/json produces: - application/json parameters: - - name: delete_contacts - in: query - description: True to delete all contacts matching the segment in addition to deleting the segment - type: boolean - name: body in: body schema: - type: 'null' + type: array + items: + type: object + properties: + email: + type: string + format: email + last_name: + type: string + description: The last name of the recipient. This is one of the default custom fields. + first_name: + type: string + description: The first name of the recipient. This is one of the default custom fields. + required: + - email + example: + - email: jones@example.com + last_name: Jones + first_name: Guy responses: - '204': + '201': description: '' schema: - type: 'null' + $ref: '#/definitions/contactdb_recipient_response' '400': - description: |- - "segment_id" : "Returned if segment_id is not valid" - "delete_contacts" : "Returned if delete_contacts is not a valid boolean" + description: '"" : "Returned if request body is not valid json"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: segment_id - message: Returned if segment_id is not valid - - field: delete_contacts - message: Returned if delete_contacts is not a valid boolean + - field: null + message: Request body is not valid json '401': description: '' schema: @@ -8034,105 +5204,49 @@ paths: errors: - field: null message: authorization required - '404': - description: '"segment_id" : "Returned if segment_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: segment_id - message: segment_id does not exist security: - Authorization: [] - patch: - summary: Update a segment + delete: + tags: + - Contacts API - Recipients + summary: Delete Recipient description: |- - **This endpoint allows you to update a segment.** + **This endpoint allows you to deletes one or more recipients.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: PATCH_contactdb-segments-segment_id + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: DELETE_contactdb-recipients consumes: - application/json produces: - application/json parameters: - - name: segment_id - in: query - description: The ID of the segment you are updating. - type: string - name: body in: body schema: - type: object - properties: - name: - type: string - list_id: - type: number - description: The list ID you would like this segment to be built from. - conditions: - type: array - description: The conditions by which this segment should be created. - items: - $ref: '#/definitions/contactdb_segments_conditions' - required: - - name + type: array + items: + type: string example: - name: The Millers - list_id: 5 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' + - recipient_id1 + - recipient_id2 responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_segments' - examples: - application/json: - id: 5 - name: The Millers - list_id: 5 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - recipient_count: 1 + type: object '400': - description: '' + description: |- + "" : "Returned if no recipients are deleted" + "" : "Returned if all of the provided recipient ids are invalid" + "" : "Returned if request body is not valid json" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: request body is not valid json - - message: invalid value is passed into one of the request body parameters - - segment_id: segment_id - message: segment id is not valid - - field: field - message: field and set value is not passed into the request body - - field: value - message: value and set value is not passed into the request body - - field: operator - message: operator and set value is not passed into the request body - - field: and_or - message: and_or is not set on more than one condition and less than all conditions - - field: and_or - message: and_or is set on all conditions - - field: and_or - message: and_or is set on the only condition passed - - field: and_or - message: and_or and set value is not passed into the request body - - field: list_id - message: the list_id is not valid - - field: name - message: the name is not valid + - message: No recipient ids provided '401': description: '' schema: @@ -8144,171 +5258,158 @@ paths: message: authorization required security: - Authorization: [] - /clients/stats: - parameters: [] - get: + post: tags: - - Stats - Advanced Stats - summary: Retrieve email statistics by client type. + - Contacts API - Recipients + summary: Add recipients description: |- - **This endpoint allows you to retrieve your email statistics segmented by client type.** + **This endpoint allows you to add a Marketing Campaigns recipient.** - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - operationId: GET_clients-stats + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: POST_contactdb-recipients consumes: - application/json produces: - application/json parameters: - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - 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 - type: string - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - responses: - '200': - description: '' + - name: body + in: body schema: type: array items: - $ref: '#/definitions/advanced_stats_opens' + type: object + properties: + email: + type: string + description: The email address of the recipient. + format: email + first_name: + type: string + description: The first name of the recipient. + last_name: + type: string + description: The last name of the recipient. + age: + type: integer + required: + - email + example: + - email: example@example.com + first_name: '' + last_name: User + age: 25 + - email: example2@example.com + first_name: Example + last_name: User + age: 25 + responses: + '201': + description: '' + schema: + $ref: '#/definitions/contactdb_recipient_response' examples: application/json: - - date: '2014-10-01' - stats: - - metrics: - opens: 1 - unique_opens: 1 - name: Gmail - type: client - - date: '2014-10-02' - stats: - - metrics: - opens: 0 - unique_opens: 0 - name: Gmail - type: client - security: - - Authorization: [] - /whitelabel/links/default: - parameters: [] - get: - tags: - - Whitelabel - Links - summary: Retrieve a Default Link Whitelabel - description: |- - **This endpoint allows you to retrieve the default link whitelabel.** - - Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: - - - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: GET_whitelabel-links-default - consumes: - - application/json - produces: - - application/json - parameters: - - name: domain - in: query - description: The domain to match against when finding a corresponding link whitelabel. - type: string - responses: - '200': + error_count: 1 + error_indices: + - 2 + new_count: 2 + persisted_recipients: + - YUBh + - bWlsbGVyQG1pbGxlci50ZXN0 + updated_count: 0 + errors: + - message: Invalid email. + error_indices: + - 2 + '400': + description: '"" : "Returned if request body is not valid json"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: Request body is not valid json + '401': description: '' schema: - $ref: '#/definitions/link_whitelabel' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net + errors: + - field: null + message: authorization required security: - Authorization: [] - '/contactdb/lists/{list_id}/recipients/{recipient_id}': + '/contactdb/recipients/{recipient_id}': parameters: - - name: list_id - in: path - description: The ID of the list that you want to add the recipient to. - required: true - type: integer - name: recipient_id in: path - description: The ID of the recipient you are adding to the list. + description: The ID of the recipient that you want to retrieve. required: true type: string - post: - summary: Add a Single Recipient to a List + get: + summary: Retrieve a single recipient description: |- - **This endpoint allows you to add a single recipient to a list.** + **This endpoint allows you to retrieve a single recipient by ID from your contact database.** The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: POST_contactdb-lists-list_id-recipients-recipient_id - consumes: - - application/json + operationId: GET_contactdb-recipients-recipient_id + consumes: [] produces: - application/json - parameters: - - name: body - in: body + parameters: [] + responses: + '200': + description: '' schema: - type: 'null' + $ref: '#/definitions/contactdb_recipient' + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' + schema: + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"recipient_id" : "Returned if record for recipient id does not exist"' + schema: + type: object + security: + - Authorization: [] + delete: + summary: Delete a Recipient + description: |- + **This endpoint allows you to delete a single recipient with the given ID from your contact database.** + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: DELETE_contactdb-recipients-recipient_id + consumes: [] + produces: + - application/json + parameters: [] responses: - '201': + '204': description: '' schema: - type: 'null' + type: object '400': - description: |- - "list_id" : "Returned if list_id is invalid" - "recipient_id" : "Returned if recipient_id is invalid" + description: '"recipient_id" : "Returned if recipient_id is not valid"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: Returned if recipient_id is invalid + - field: null + message: recipient not found '401': description: '' schema: @@ -8319,138 +5420,234 @@ paths: - field: null message: authorization required '404': - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" + description: '"recipient_id" : "Returned if record for recipient id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist + - field: null + message: recipient_id is not valid security: - Authorization: [] - delete: - summary: Delete a Single Recipient from a Single List + '/campaigns/{campaign_id}/schedules/test': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + summary: Send a Test Campaign description: |- - **This endpoint allows you to delete a single recipient from a list.** + **This endpoint allows you to send a test campaign.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: DELETE_contactdb-lists-list_id-recipients-recipient_id + To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns-campaign_id-schedules-test consumes: - application/json produces: - application/json parameters: - - name: list_id - in: query - description: The ID of the list you are taking this recipient away from. - required: true - type: number - - name: recipient_id - in: query - description: The ID of the recipient to take off the list. - required: true - type: number - name: body in: body schema: - type: 'null' + type: object + properties: + to: + type: string + description: The email address that should receive the test campaign. + format: email + required: + - to + example: + to: your.email@example.com responses: '204': description: '' schema: - type: 'null' + title: Send a Test Campaign request + type: object + properties: + to: + type: string + required: + - to '400': description: |- - "list_id" : "Returned if list_id is not valid" - "recipient_id" : "Returned if recipient_id is not valid" + "": "The JSON you have submitted cannot be parsed." + "to": "Please provide an email address to which the test should be sent." + "to": "You can only send tests to 10 addresses at a time." + "subject": "Please add a subject to your campaign before sending a test." + "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." + "sender_id": "Please assign a sender identity to your campaign before sending a test." schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: no valid recipients were provided + - field: send_at + message: Please choose a future time for sending your campaign. + - field: null + message: The JSON you have submitted cannot be parsed. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + '404': + description: '"": "not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: not found + security: + - Authorization: [] + '/campaigns/{campaign_id}': + parameters: + - name: campaign_id + in: path + description: The id of the campaign you would like to retrieve. + required: true + type: integer + get: + summary: Retrieve a single campaign + description: |- + **This endpoint allows you to retrieve a specific campaign.** + + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: GET_campaigns-campaign_id + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + categories: + type: array + items: + type: string + custom_unsubscribe_url: + type: string + html_content: + type: string + id: + type: integer + ip_pool: + type: string + list_ids: + type: array + items: + type: integer + plain_content: + type: string + segment_ids: + type: array + items: + type: integer + sender_id: + type: integer + status: + type: string + subject: + type: string + suppression_group_id: + type: integer + title: + type: string + examples: + application/json: + categories: + - spring line + custom_unsubscribe_url: '' + html_content:

Check out our spring line!

+ id: 986724 + ip_pool: marketing + list_ids: + - 110 + plain_content: Check out our spring line! + segment_ids: + - 110 + sender_id: 124451 + status: Draft + subject: New Products for Spring! + suppression_group_id: 42 + title: March Newsletter '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - field: null message: authorization required '404': - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" + description: '"": "not found"' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist + - field: null + message: not found security: - Authorization: [] - '/contactdb/recipients/{recipient_id}': - parameters: - - name: recipient_id - in: path - description: The ID of the recipient that you want to retrieve. - required: true - type: string - get: - summary: Retrieve a single recipient + delete: + summary: Delete a Campaign description: |- - **This endpoint allows you to retrieve a single recipient by ID from your contact database.** + **This endpoint allows you to delete a specific campaign.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-recipients-recipient_id - consumes: - - application/json + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: DELETE_campaigns-campaign_id + consumes: [] produces: - application/json parameters: [] responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/contactdb_recipient' - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - schema: - type: object + type: 'null' '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - field: null message: authorization required '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' + description: '"": "not found"' schema: type: object security: - Authorization: [] - delete: - summary: Delete a Recipient + patch: + summary: Update a Campaign description: |- - **This endpoint allows you to delete a single recipient with the given ID from your contact database.** + Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: DELETE_contactdb-recipients-recipient_id + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: PATCH_campaigns-campaign_id consumes: - application/json produces: @@ -8459,21 +5656,109 @@ paths: - name: body in: body schema: - type: 'null' + title: Update a Campaign request + type: object + properties: + title: + type: string + description: The title of the campaign. + subject: + type: string + description: The subject line for your campaign. + categories: + type: array + description: The categories you want to tag on this campaign. + items: + type: string + html_content: + type: string + description: The HTML content of this campaign. + plain_content: + type: string + description: The plain content of this campaign. + required: + - title + - subject + - categories + - html_content + - plain_content + example: + title: May Newsletter + subject: New Products for Summer! + categories: + - summer line + html_content:

Check out our summer line!

+ plain_content: Check out our summer line! responses: - '204': + '200': description: '' schema: - type: object + $ref: '#/definitions/campaign_response' + examples: + application/json: + id: 986724 + title: May Newsletter + subject: New Products for Summer! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - summer line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:

Check out our summer line!

+ plain_content: Check out our summer line! + status: Draft '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: + - field: title + message: title can't be blank + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - field: null - message: recipient not found + message: The JSON you have submitted cannot be parsed. '401': description: '' schema: @@ -8483,34 +5768,43 @@ paths: errors: - field: null message: authorization required + '403': + description: '"": "You may only update a campaign when it is in draft mode."' + schema: + type: object + examples: + application/json: + errors: + - field: null + message: You may only update a campaign when it is in draft mode. '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: recipient_id is not valid + message: not found security: - Authorization: [] - '/campaigns/{campaign_id}/schedules/test': - parameters: - - name: campaign_id - in: path - required: true - type: integer - post: - summary: Send a Test Campaign + /user/profile: + parameters: [] + patch: + tags: + - Users API + summary: Update a user's profile description: |- - **This endpoint allows you to send a test campaign.** + **This endpoint allows you to update your current profile details.** - To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - For more information: + For more information about your user profile: - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns-campaign_id-schedules-test + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + + It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. + operationId: PATCH_user-profile consumes: - application/json produces: @@ -8519,55 +5813,119 @@ paths: - name: body in: body schema: - type: object - properties: - to: - type: string - description: The email address that should receive the test campaign. - format: email - required: - - to + $ref: '#/definitions/user_profile' example: - to: your.email@example.com + first_name: Example + last_name: User + city: Orange + responses: + '200': + description: '' + schema: + $ref: '#/definitions/user_profile' + examples: + application/json: + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Example + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + get: + tags: + - Users API + summary: Get a user's profile + description: |- + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: GET_user-profile + consumes: [] + produces: + - application/json + parameters: [] responses: - '204': + '200': description: '' schema: - title: Send a Test Campaign request + title: GET User Profile response type: object properties: - to: + address: + type: string + description: The user's address. + address2: + type: string + description: The second line of the user's address. + city: + type: string + description: The user's city. + company: + type: string + description: The name of the user's company. + country: + type: string + description: The user's country. + first_name: + type: string + description: The user's first name. + last_name: + type: string + description: The user's last name. + phone: + type: string + description: The user's phone number. + state: type: string + description: The user's state. + website: + type: string + description: The user's website URL. + zip: + type: string + description: The user's zip code. required: - - to - '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "to": "Please provide an email address to which the test should be sent." - "to": "You can only send tests to 10 addresses at a time." - "subject": "Please add a subject to your campaign before sending a test." - "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." - "sender_id": "Please assign a sender identity to your campaign before sending a test." - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: send_at - message: Please choose a future time for sending your campaign. - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + - address + - city + - company + - country + - first_name + - last_name + - phone + - state + - website + - zip examples: application/json: - errors: - - field: null - message: not found + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Test + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' security: - Authorization: [] '/mail/batch/{batch_id}': @@ -8587,8 +5945,7 @@ paths: * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) operationId: GET_mail-batch-batch_id - consumes: - - application/json + consumes: [] produces: - application/json parameters: [] @@ -8636,23 +5993,18 @@ paths: * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) operationId: GET_suppression-bounces - consumes: - - application/json + consumes: [] produces: - application/json parameters: - name: start_time in: query description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). - type: number + type: integer - name: end_time in: query description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). - type: number - - name: Allow - in: header - description: '' - type: string + type: integer responses: '200': description: '' @@ -8748,6 +6100,62 @@ paths: - Authorization: [] /subusers: parameters: [] + get: + tags: + - Subusers API + summary: List all Subusers + description: |- + This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: GET_subusers + consumes: [] + produces: + - application/json + parameters: + - name: username + in: query + description: The username of this subuser. + type: string + - name: limit + in: query + description: The number of results you would like to get in each request. + type: integer + - name: offset + in: query + description: The number of subusers to skip. + type: integer + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/subuser' + examples: + application/json: + - 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. + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] post: tags: - Subusers API @@ -8848,54 +6256,54 @@ paths: - message: unable to validate IPs at this time security: - Authorization: [] - get: - tags: - - Subusers API - summary: List all Subusers + '/subusers/{subuser_name}': + parameters: + - name: subuser_name + in: path + required: true + type: string + patch: + summary: Enable/disable a subuser description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + This endpoint allows you to enable or disable a subuser. For more information about Subusers: * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: GET_subusers + operationId: PATCH_subusers-subuser_name consumes: - application/json produces: - application/json parameters: - - name: username - in: query - description: The username of this subuser. - type: string - - name: limit - in: query - description: The number of results you would like to get in each request. - type: number - - name: offset - in: query - description: The number of subusers to skip. - type: number + - name: body + in: body + 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: - '200': + '204': description: '' schema: - type: array - items: - $ref: '#/definitions/subuser' + type: object + properties: {} + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - disabled: false - email: example@example.com - id: 1234 - username: example_subuser - - disabled: false - email: example2@example.com - id: 1234 - username: example_subuser2 + errors: + - message: invalid username + - message: no fields provided '401': - description: Unexpected error in API call. See HTTP response body for details. + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: @@ -8903,72 +6311,36 @@ paths: errors: - field: null message: authorization required - security: - - Authorization: [] - '/contactdb/segments/{segment_id}/recipients': - parameters: - - name: segment_id - in: path - description: The ID of the segment from which you want to retrieve recipients. - required: true - type: integer - get: - summary: Retrieve recipients on a segment - description: |- - **This endpoint allows you to retrieve all of the recipients in a segment with the given ID.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: GET_contactdb-segments-segment_id-recipients - consumes: - - application/json - produces: - - application/json - parameters: - - name: page - in: query - type: integer - - name: page_size - in: query - type: integer - responses: - '200': + '500': description: '' schema: - title: List Recipients On a Segment response - type: object - properties: - recipients: - type: array - items: - $ref: '#/definitions/contactdb_recipient' - required: - - recipients + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - recipients: - - created_at: 1422313607 - email: jones@example.com - first_name: null - id: YUBh - last_clicked: null - last_emailed: null - last_name: Jones - last_opened: null - updated_at: 1422313790 - custom_fields: - - id: 23 - name: pet - value: Indiana - type: text - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" + errors: + - message: unable to enable user + security: + - Authorization: [] + delete: + summary: Delete a subuser + description: |- + This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: DELETE_subusers-subuser_name + consumes: [] + produces: + - application/json + parameters: [] + responses: + '204': + description: '' schema: type: object + properties: {} '401': description: '' schema: @@ -8978,12 +6350,6 @@ paths: errors: - field: null message: authorization required - '404': - description: |- - "segment_id" : "Returned if segment_id is not valid" - "segment_id" : "Returned if segment_id does not exist" - schema: - type: object security: - Authorization: [] /whitelabel/ips: @@ -9063,8 +6429,7 @@ paths: For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). operationId: GET_whitelabel-ips - consumes: - - application/json + consumes: [] produces: - application/json parameters: @@ -9134,8 +6499,7 @@ paths: Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). operationId: GET_partner_settings - consumes: - - application/json + consumes: [] produces: - application/json parameters: @@ -9184,6 +6548,77 @@ paths: description: A description of a partner. security: - Authorization: [] + /partner_settings/new_relic: + parameters: [] + patch: + summary: Updates New Relic partner settings. + description: |- + **This endpoint allows you to update or change your New Relic partner settings.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + operationId: PATCH_partner_settings-new_relic + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + license_key: + type: string + description: The license key for your New Relic account. + enabled: + type: boolean + description: Indicates if this partner setting is enabled. + enable_subuser_statistics: + type: boolean + description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. + example: + license_key: '' + enabled: true + enable_subuser_statistics: true + responses: + '200': + description: '' + schema: + $ref: '#/definitions/partner_settings_new_relic' + examples: + application/json: + enable_subuser_statistics: true + enabled: true + license_key: '' + security: + - Authorization: [] + get: + summary: Returns all New Relic partner settings. + description: |- + **This endpoint allows you to retrieve your current New Relic partner settings.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + operationId: GET_partner_settings-new_relic + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/partner_settings_new_relic' + examples: + application/json: + enable_subuser_statistics: false + enabled: true + license_key: '' + security: + - Authorization: [] /whitelabel/domains/subuser: parameters: [] delete: @@ -9204,19 +6639,12 @@ paths: |---|---|---|---| | username | string | required | Username for the subuser to find associated whitelabels for. | operationId: DELETE_whitelabel-domains-subuser - consumes: - - application/json + consumes: [] produces: [] - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '204': description: '' - schema: - type: object security: - Authorization: [] get: @@ -9237,8 +6665,7 @@ paths: |---|---|---| | username | string | Username of the subuser to find associated whitelabels for. | operationId: GET_whitelabel-domains-subuser - consumes: - - application/json + consumes: [] produces: - application/json parameters: [] @@ -9283,6 +6710,113 @@ paths: valid: false security: - Authorization: [] + /user/scheduled_sends: + parameters: [] + post: + summary: Cancel or pause a scheduled send + description: |- + **This endpoint allows you to cancel or pause an email that has been scheduled to be sent.** + + If the maximum number of cancellations/pauses are added, HTTP 400 will + be returned. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: POST_user-scheduled_sends + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + title: Cancel or pause a scheduled send request + type: object + properties: + batch_id: + type: string + description: The batch ID is the identifier that your scheduled mail sends share. + pattern: '^[a-zA-Z0-9]' + status: + type: string + default: pause + description: 'The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}' + enum: + - pause + - cancel + required: + - batch_id + - status + example: + batch_id: YOUR_BATCH_ID + status: pause + responses: + '201': + description: '' + schema: + $ref: '#/definitions/user_scheduled_send_status' + '400': + description: |- + "" : "max limit reached" + "batch_id" : "invalid batch id" + "batch_id" : "a status for this batch id exists, try PATCH to update the status" + schema: + type: object + examples: + application/json: + errors: + - field: null + message: max limit reached + - field: batch_id + message: invalid batch id + - field: batch_id + message: 'a status for this batch id exists, try PATCH to update the status' + '401': + description: '' + schema: + type: object + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + get: + summary: Retrieve all scheduled sends + description: |- + **This endpoint allows you to retrieve all cancel/paused scheduled send information.** + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: GET_user-scheduled_sends + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/user_scheduled_send_status' + examples: + application/json: + - batch_id: YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg + status: cancel + - batch_id: UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2 + status: cancel + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] /contactdb/custom_fields: parameters: [] post: @@ -9351,8 +6885,7 @@ paths: The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). operationId: GET_contactdb-custom_fields - consumes: - - application/json + consumes: [] produces: - application/json parameters: [] @@ -9415,8 +6948,7 @@ paths: The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). operationId: GET_contactdb-custom_fields-custom_field_id - consumes: - - application/json + consumes: [] produces: - application/json parameters: [] @@ -9464,15 +6996,10 @@ paths: The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). operationId: DELETE_contactdb-custom_fields-custom_field_id - consumes: - - application/json + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '202': description: '' @@ -9522,15 +7049,14 @@ paths: The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. operationId: GET_contactdb-lists-list_id - consumes: - - application/json + consumes: [] produces: - application/json parameters: - name: list_id in: query description: The ID of the list to retrieve. - type: number + type: integer responses: '200': description: '' @@ -9586,7 +7112,7 @@ paths: in: query description: The ID of the list you are updating. required: true - type: number + type: integer - name: body in: body schema: @@ -9634,8 +7160,7 @@ paths: The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. operationId: DELETE_contactdb-lists-list_id - consumes: - - application/json + consumes: [] produces: - application/json parameters: @@ -9646,10 +7171,6 @@ paths: enum: - true - false - - name: body - in: body - schema: - type: 'null' responses: '202': description: '' @@ -9667,7 +7188,265 @@ paths: - field: delete_contacts message: delete_contacts not a bool - field: list_id - message: Returned if list_id is not valid + message: Returned if list_id is not valid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: 'List not found: 5' + security: + - Authorization: [] + '/contactdb/recipients/{recipient_id}/lists': + parameters: + - name: recipient_id + in: path + description: The ID of the recipient for whom you are retrieving lists. + required: true + type: string + get: + summary: Retrieve the lists that a recipient is on + description: |- + **This endpoint allows you to retrieve the lists that a given recipient belongs to.** + + Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-recipients-recipient_id-lists + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + lists: + type: array + items: + $ref: '#/definitions/contactdb_list' + examples: + application/json: + lists: + - id: 1234 + name: Example list + recipient_count: 42 + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: recipient ID is invalid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"recipient_id" : "Returned if record for the recipient id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: recipient id not found + security: + - Authorization: [] + /contactdb/segments: + parameters: [] + get: + tags: + - Contacts API - Segments + summary: Retrieve all segments + description: |- + **This endpoint allows you to retrieve all of your segments.** + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: GET_contactdb-segments + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + title: List All Segments response + type: object + properties: + segments: + type: array + items: + $ref: '#/definitions/contactdb_segments' + required: + - segments + examples: + application/json: + segments: + - id: 1234 + name: Age segments < 25 + conditions: + - field: age + value: '25' + operator: lt + recipient_count: 8 + - id: 2345 + name: email address - gmail + conditions: + - field: email + value: '@gmail.com' + operator: contains + recipient_count: 0 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + post: + tags: + - Contacts API - Segments + summary: Create a Segment + description: |- + **This endpoint allows you to create a segment.** + + All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment. + + List Id: + + * Send this to segment from an existing list + * Don't send this in order to segment from your entire contactdb. + + Valid operators for create and update depend on the type of the field you are segmenting: + + * **Dates:** "eq", "ne", "lt" (before), "gt" (after) + * **Text:** "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value) + * **Numbers:** "eq", "lt", "gt" + * **Email Clicks and Opens:** "eq" (opened), "ne" (not opened) + + Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. + + Segments may contain multiple condtions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or". + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: POST_contactdb-segments + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/contactdb_segments' + example: + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + - field: last_clicked + value: 01/02/2015 + operator: gt + and_or: and + - field: clicks.campaign_identifier + value: '513' + operator: eq + and_or: or + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contactdb_segments_with_id' + examples: + application/json: + id: 1 + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + - field: last_clicked + value: 01/02/2015 + operator: gt + and_or: and + - field: clicks.campaign_identifier + value: '513' + operator: eq + and_or: or + recipient_count: 0 + '400': + description: |- + "name" : "Returned if the name is not valid" + "list_id" : "Returned if the list_id is not valid" + "and_or" : "Returned if and_or and set value is not passed into the request body" + "and_or" : "Returned if and_or is set on the only condition passed" + "and_or" : "Returned if and_or is set on all conditions" + "and_or" : "Returned if and_or is not set on more than one condition and less than all conditions" + "operator" : "Returned if operator and set value is not passed into the request body" + "value" : "Returned if value and set value is not passed into the request body" + "field" : "Returned if field and set value is not passed into the request body" + "" : "Returned if request body is not valid json" + "" : "Returned if invalid value is passed into one of the request body parameters" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: request body is not valid json + - message: invalid value is passed into one of the request body parameters + - field: field + message: field and set value is not passed into the request body + - field: value + message: value and set value is not passed into the request body + - field: operator + message: operator and set value is not passed into the request body + - field: and_or + message: and_or is not set on more than one condition and less than all conditions + - field: and_or + message: and_or is set on all conditions + - field: and_or + message: and_or is set on the only condition passed + - field: and_or + message: and_or and set value is not passed into the request body + - field: list_id + message: the list_id is not valid + - field: name + message: the name is not valid '401': description: '' schema: @@ -9677,174 +7456,206 @@ paths: errors: - field: null message: authorization required - '404': - description: '"list_id" : "Returned if list_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: 'List not found: 5' security: - Authorization: [] - /contactdb/recipients/search: + /whitelabel/links/subuser: parameters: [] get: tags: - - Contacts API - Recipients - summary: Retrieve recipients matching search criteria + - Whitelabel - Links + summary: Retrieve Associated Link Whitelabel description: |- - **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** + **This endpoint allows you to retrieve the associated link whitelabel for a subuser.** - field_name: + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. - * is a variable that is substituted for your actual custom field name from your recipient. - * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) - * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert - your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to - Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through - Mon, 02 Feb 2015 23:59:59 GMT. + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-recipients-search - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: GET_whitelabel-links-subuser + consumes: [] produces: - application/json parameters: - - name: '{field_name}' + - name: username in: query + description: The username of the subuser to retrieve associated link whitelabels for. + required: true type: string responses: '200': description: '' schema: - type: object - properties: - recipients: - type: array - items: - $ref: '#/definitions/contactdb_recipient' - examples: - application/json: - recipients: - - created_at: 1422313607 - email: jones@example.com - first_name: null - id: YUBh - last_clicked: null - last_emailed: null - last_name: Jones - last_opened: null - updated_at: 1422313790 - custom_fields: - - id: 23 - name: pet - value: Fluffy - type: text - '400': - description: |- - "" : "Returned if no search params are specified" - "field" : "Returned if the provided field is invalid or does not exist" - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/link_whitelabel' examples: application/json: - errors: - - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' - - message: No search params are specified - '401': + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + security: + - Authorization: [] + delete: + tags: + - Whitelabel - Links + summary: Disassociate a Link Whitelabel + description: |- + **This endpoint allows you to disassociate a link whitelabel from a subuser.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: DELETE_whitelabel-links-subuser + consumes: [] + produces: [] + parameters: + - name: username + in: query + description: The username of the subuser account that you want to disassociate a link whitelabel from. + required: true + type: string + responses: + '204': description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required security: - Authorization: [] - '/contactdb/recipients/{recipient_id}/lists': + '/whitelabel/domains/{domain_id}': parameters: - - name: recipient_id + - name: domain_id in: path - description: The ID of the recipient for whom you are retrieving lists. + description: The id of the domain whitelabel. required: true - type: string - get: - summary: Retrieve the lists that a recipient is on + type: number + patch: + summary: Update a domain whitelabel. description: |- - **This endpoint allows you to retrieve the lists that a given recipient belongs to.** + **This endpoint allows you to update the settings for a domain whitelabel.** - Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-recipients-recipient_id-lists + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: PATCH_whitelabel-domains-domain_id consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + default: + type: boolean + default: false + description: Indicates whether this domain whitelabel should be considered the default. + custom_spf: + type: boolean + default: false + description: Indicates whether to generate a custom SPF record for manual security. + example: + default: false + custom_spf: true responses: '200': description: '' schema: + title: Update a Domain response type: object properties: - lists: - type: array - items: - $ref: '#/definitions/contactdb_list' - examples: - application/json: - lists: - - id: 1234 - name: Example list - recipient_count: 42 - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: recipient ID is invalid - '401': + default false: + description: Inidcates whether this domain whitelabel should be considered the default. Defaults to false. + type: boolean + custom_spf false: + description: Indicates whether to generate a custom SPF record for manual security. Defaults to false. + type: boolean + security: + - Authorization: [] + delete: + summary: Delete a domain whitelabel. + description: |- + **This endpoint allows you to delete a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: DELETE_whitelabel-domains-domain_id + consumes: [] + produces: [] + parameters: [] + responses: + '204': description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"recipient_id" : "Returned if record for the recipient id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: recipient id not found security: - Authorization: [] - /contactdb/segments: - parameters: [] get: - tags: - - Contacts API - Segments - summary: Retrieve all segments + summary: Retrieve a domain whitelabel. + description: | + **This endpoint allows you to retrieve a specific domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: GET_whitelabel-domains-domain_id + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/whitelabel::domain' + security: + - Authorization: [] + '/templates/{template_id}/versions/{version_id}/activate': + parameters: + - name: template_id + in: path + required: true + type: string + - name: version_id + in: path + required: true + type: string + post: + summary: Activate a transactional template version. description: |- - **This endpoint allows you to retrieve all of your segments.** + **This endpoint allows you to activate a version of one of your templates.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: GET_contactdb-segments - consumes: - - application/json + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: POST_templates-template_id-versions-version_id-activate + consumes: [] produces: - application/json parameters: [] @@ -9852,280 +7663,202 @@ paths: '200': description: '' schema: - title: List All Segments response type: object properties: - segments: - type: array - items: - $ref: '#/definitions/contactdb_segments' + id: + type: string + description: The ID of the template version. + updated_at: + type: string + description: The date and time that the version was last updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' required: - - segments - examples: - application/json: - segments: - - id: 1234 - name: Age segments < 25 - conditions: - - field: age - value: '25' - operator: lt - recipient_count: 8 - - id: 2345 - name: email address - gmail - conditions: - - field: email - value: '@gmail.com' - operator: contains - recipient_count: 0 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + - id + - updated_at examples: application/json: - errors: - - field: null - message: authorization required + id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 + template_id: e3a61852-1acb-4b32-a1bc-b44b3814ab78 + active: 1 + name: example_version_name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> + updated_at: '2014-06-12 11:33:00' security: - Authorization: [] - post: - tags: - - Contacts API - Segments - summary: Create a Segment + '/templates/{template_id}/versions/{version_id}': + parameters: + - name: template_id + in: path + required: true + type: string + - name: version_id + in: path + required: true + type: string + get: + summary: Retrieve a specific transactional template version. description: |- - **This endpoint allows you to create a segment.** - - All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment. - - List Id: - - * Send this to segment from an existing list - * Don't send this in order to segment from your entire contactdb. - - Valid operators for create and update depend on the type of the field you are segmenting: - - * **Dates:** "eq", "ne", "lt" (before), "gt" (after) - * **Text:** "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value) - * **Numbers:** "eq", "lt", "gt" - * **Email Clicks and Opens:** "eq" (opened), "ne" (not opened) - - Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. + **This endpoint allows you to retrieve a specific version of a template.** - Segments may contain multiple condtions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or". + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: POST_contactdb-segments - consumes: - - application/json + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: GET_templates-template_id-versions-version_id + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/contactdb_segments' - example: - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - - field: last_clicked - value: 01/02/2015 - operator: gt - and_or: and - - field: clicks.campaign_identifier - value: '513' - operator: eq - and_or: or + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_segments_with_id' - examples: - application/json: - id: 1 - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - - field: last_clicked - value: 01/02/2015 - operator: gt - and_or: and - - field: clicks.campaign_identifier - value: '513' - operator: eq - and_or: or - recipient_count: 0 - '400': - description: |- - "name" : "Returned if the name is not valid" - "list_id" : "Returned if the list_id is not valid" - "and_or" : "Returned if and_or and set value is not passed into the request body" - "and_or" : "Returned if and_or is set on the only condition passed" - "and_or" : "Returned if and_or is set on all conditions" - "and_or" : "Returned if and_or is not set on more than one condition and less than all conditions" - "operator" : "Returned if operator and set value is not passed into the request body" - "value" : "Returned if value and set value is not passed into the request body" - "field" : "Returned if field and set value is not passed into the request body" - "" : "Returned if request body is not valid json" - "" : "Returned if invalid value is passed into one of the request body parameters" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: request body is not valid json - - message: invalid value is passed into one of the request body parameters - - field: field - message: field and set value is not passed into the request body - - field: value - message: value and set value is not passed into the request body - - field: operator - message: operator and set value is not passed into the request body - - field: and_or - message: and_or is not set on more than one condition and less than all conditions - - field: and_or - message: and_or is set on all conditions - - field: and_or - message: and_or is set on the only condition passed - - field: and_or - message: and_or and set value is not passed into the request body - - field: list_id - message: the list_id is not valid - - field: name - message: the name is not valid - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + id: + type: string + description: The ID of the template version. + updated_at: + type: string + description: The date and time that the template version was last updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at examples: application/json: - errors: - - field: null - message: authorization required + id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f + template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d + active: 1 + name: version 1 name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> + updated_at: '2014-03-19 18:56:33' security: - Authorization: [] - /whitelabel/links/subuser: - parameters: [] - get: - tags: - - Whitelabel - Links - summary: Retrieve Associated Link Whitelabel + delete: + summary: Delete a transactional template version. description: |- - **This endpoint allows you to retrieve the associated link whitelabel for a subuser.** - - Link whitelables can be associated with subusers from the parent account. This functionality allows - subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account - must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. - - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: GET_whitelabel-links-subuser - consumes: - - application/json - produces: - - application/json - parameters: - - name: username - in: query - description: The username of the subuser to retrieve associated link whitelabels for. - required: true - type: string + **This endpoint allows you to delete one of your transactional template versions.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: DELETE_templates-template_id-versions-version_id + consumes: [] + produces: [] + parameters: [] responses: - '200': + '204': description: '' - schema: - $ref: '#/definitions/link_whitelabel' - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net security: - Authorization: [] - delete: - tags: - - Whitelabel - Links - summary: Disassociate a Link Whitelabel + patch: + summary: Edit a transactional template version. description: |- - **This endpoint allows you to disassociate a link whitelabel from a subuser.** + **This endpoint allows you to edit a version of one of your transactional templates.** - Link whitelables can be associated with subusers from the parent account. This functionality allows - subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account - must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: DELETE_whitelabel-links-subuser + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: PATCH_templates-template_id-versions-version_id consumes: - application/json - produces: [] + produces: + - application/json parameters: - - name: username - in: query - description: The username of the subuser account that you want to disassociate a link whitelabel from. - required: true - type: string - name: body in: body schema: - type: 'null' + type: object + properties: + active: + type: integer + description: Indicates if the template version is active. + name: + type: string + description: The name of the template version. + html_content: + type: string + description: The HTML content of the template version. + plain_content: + type: string + description: The text/plain content of the template version. + subject: + type: string + description: The subject of the template version. + example: + active: 1 + name: updated_example_name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> responses: - '204': + '200': description: '' schema: type: object + properties: + id: + type: string + description: The ID of the template version. + updated_at: + type: string + description: The date and time that the template version was last updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at + examples: + application/json: + id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f + template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d + active: 1 + name: version 1 name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> + updated_at: '2014-03-19 18:56:33' security: - Authorization: [] - '/whitelabel/links/{link_id}/subuser': + '/templates/{template_id}/versions': parameters: - - name: link_id + - name: template_id in: path - description: The id of the link whitelabel you want to associate. required: true - type: integer + type: string post: - summary: Associate a Link Whitelabel - description: |- - **This endpoint allows you to associate a link whitelabel with a subuser account.** - - Link whitelables can be associated with subusers from the parent account. This functionality allows - subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account - must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + summary: Create a new transactional template version. + description: | + **This endpoint allows you to create a new version of a template.** - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: POST_whitelabel-links-link_id-subuser + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: POST_templates-template_id-versions consumes: - application/json produces: @@ -10133,64 +7866,117 @@ paths: parameters: - name: body in: body + schema: + $ref: '#/definitions/transactional_template_version' + example: + template_id: ddb96bbc-9b92-425e-8979-99464621b543 + active: 1 + name: example_version_name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> + responses: + '201': + description: '' schema: type: object properties: - username: + id: type: string - description: The username of the subuser account that you want to associate the link whitelabel with. - example: - username: jane@example.com + description: The id of the new transactional template version. + updated_at: + type: string + description: The date and time that this transactional template version was updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at + examples: + application/json: + id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 + template_id: ddb96bbc-9b92-425e-8979-99464621b543 + active: 1 + name: example_version_name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> + updated_at: '2014-03-19 18:56:33' + security: + - Authorization: [] + /contactdb/recipients/billable_count: + parameters: [] + get: + summary: Retrieve the count of billable recipients + description: |- + **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** + + You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-recipients-billable_count + consumes: [] + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/link_whitelabel' + $ref: '#/definitions/contactdb_recipient_count' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net + recipient_count: 1234 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + /ips/warmup: + parameters: [] + get: + tags: + - IP Warmup + summary: Retrieve all IPs currently in warmup + description: |- + **This endpoint allows you to retrieve all of your IP addresses that are currently warming up.** + + SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + + For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). + operationId: GET_ips-warmup + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/ip_warmup_response' + examples: + application/json: + - ip: 0.0.0.0 + start_date: 1409616000 security: - Authorization: [] - '/whitelabel/domains/{id}/ips': - parameters: - - name: id - in: path - required: true - type: string post: tags: - - Whitelabel - Domains - summary: Add an IP to a domain whitelabel. + - IP Warmup + summary: Add an IP to warmup description: |- - **This endpoint allows you to add an IP address to a domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to enter an IP address into warmup mode.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | ID of the domain to which you are adding an IP | - operationId: POST_whitelabel-domains-id-ips + For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). + operationId: POST_ips-warmup consumes: - application/json produces: @@ -10203,74 +7989,77 @@ paths: properties: ip: type: string - description: IP to associate with the domain. Used for manually specifying IPs for custom SPF. - required: - - ip + description: The IP address that you want to begin warming up. example: - ip: 192.168.0.1 + ip: 0.0.0.0 responses: '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' + $ref: '#/definitions/ip_warmup_response' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false + - ip: 0.0.0.0 + start_date: 1409616000 + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The errors that were encountered. + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the IP couldn't entered into warmup mode. + examples: + application/json: + errors: + - field: null + message: resource not found security: - Authorization: [] - '/whitelabel/domains/{domain_id}/subuser': - parameters: - - name: domain_id - in: path - required: true - type: string - post: - summary: Associate a domain whitelabel with a given user. + /mail_settings/bounce_purge: + parameters: [] + get: + summary: Retrieve bounce purge mail settings description: |- - **This endpoint allows you to associate a specific domain whitelabel with a subuser.** + **This endpoint allows you to retrieve your current bounce purge settings.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-bounce_purge + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/mail_settings_bounce_purge' + examples: + application/json: + enabled: false + soft_bounces: 1234 + hard_bounces: null + security: + - Authorization: [] + patch: + summary: Update bounce purge mail settings + description: |- + **This endpoint allows you to update your current bounce purge settings.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | domain_id | integer | ID of the domain whitelabel to associate with the subuser. | - operationId: POST_whitelabel-domains-domain_id-subuser + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-bounce_purge consumes: - application/json produces: @@ -10279,212 +8068,131 @@ paths: - name: body in: body schema: - type: object - properties: - username: - type: string - description: Username to associate with the domain whitelabel. - required: - - username + $ref: '#/definitions/mail_settings_bounce_purge' example: - username: jane@example.com + enabled: true + hard_bounces: 5 + soft_bounces: 5 responses: - '201': + '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' + $ref: '#/definitions/mail_settings_bounce_purge' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: mail@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false + enabled: false + hard_bounces: null + soft_bounces: null security: - Authorization: [] - '/templates/{template_id}/versions/{version_id}/activate': + '/suppression/blocks/{email}': parameters: - - name: template_id - in: path - required: true - type: string - - name: version_id + - name: email in: path + description: The blocked email address that you want to delete. required: true type: string - post: - summary: Activate a transactional template version. + delete: + tags: + - Blocks API + summary: Delete a specific block description: |- - **This endpoint allows you to activate a version of one of your templates.** + **This endpoint allows you to delete a specific email address from your blocks list.** - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: DELETE_suppression-blocks-email + consumes: [] + produces: [] + parameters: [] + responses: + '204': + description: '' + get: + tags: + - Blocks API + summary: Retrieve a specific block + description: |- + **This endpoint allows you to retrieve a specific email address from your blocks list.** - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - operationId: POST_templates-template_id-versions-version_id-activate - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: GET_suppression-blocks-email + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '200': description: '' schema: - type: object - properties: - id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_template_version' - required: - - id - - updated_at + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the block was created. + email: + type: string + description: The email address of the recipient that was blocked. + reason: + type: string + description: The reason why the email was blocked. + status: + type: string + description: The status of the block. + required: + - created + - email + - reason examples: application/json: - id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 - template_id: e3a61852-1acb-4b32-a1bc-b44b3814ab78 - active: 1 - name: example_version_name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> - updated_at: '2014-06-12 11:33:00' + - created: 1443651154 + email: user1@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 security: - Authorization: [] - '/whitelabel/domains/{id}/ips/{ip}': - parameters: - - name: id - in: path - required: true - type: string - - name: ip - in: path - required: true - type: string - delete: + /templates: + parameters: [] + get: tags: - - Whitelabel - Domains - summary: Remove an IP from a domain whitelabel. + - Transactional Templates + summary: Retrieve all transactional templates. description: |- - **This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to retrieve all transactional templates.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | ID of the domain whitelabel to delete the IP from. | - | ip | string | IP to remove from the domain whitelabel. | - operationId: DELETE_whitelabel-domains-id-ips-ip - consumes: - - application/json + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: GET_templates + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: mail@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false + type: array + items: + $ref: '#/definitions/transactional_template' security: - Authorization: [] - '/templates/{template_id}/versions': - parameters: - - name: template_id - in: path - required: true - type: string post: - summary: Create a new transactional template version. - description: | - **This endpoint allows you to create a new version of a template.** + tags: + - Transactional Templates + summary: Create a transactional template. + description: |- + **This endpoint allows you to create a transactional template.** - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - operationId: POST_templates-template_id-versions + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: POST_templates consumes: - application/json produces: @@ -10493,41 +8201,26 @@ paths: - name: body in: body schema: - $ref: '#/definitions/transactional_template_version' + type: object + properties: + name: + type: string + description: The name for the new transactional template. + maxLength: 100 + required: + - name example: - template_id: ddb96bbc-9b92-425e-8979-99464621b543 - active: 1 - name: example_version_name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> + name: example_name responses: '201': description: '' schema: - type: object - properties: - id: - type: string - description: The id of the new transactional template version. - updated_at: - type: string - description: The date and time that this transactional template version was updated. - Transactional Template Version: - $ref: '#/definitions/transactional_template_version' - required: - - id - - updated_at + $ref: '#/definitions/transactional_template' examples: application/json: - id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 - template_id: ddb96bbc-9b92-425e-8979-99464621b543 - active: 1 - name: example_version_name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> - updated_at: '2014-03-19 18:56:33' + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: example_name + versions: [] security: - Authorization: [] /mail/batch: @@ -10545,15 +8238,10 @@ paths: * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) operationId: POST_mail-batch - consumes: - - application/json + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '201': description: '' @@ -10593,40 +8281,150 @@ paths: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - type: array - items: - type: string - format: ipv4 - example: - - 127.0.0.1 + parameters: + - name: body + in: body + 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: '' + schema: + type: object + properties: + ips: + type: array + description: The IP addresses that are assigned to the subuser. + items: + type: string + format: ipv4 + examples: + application/json: + ips: + - 127.0.0.1 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '/whitelabel/ips/{id}': + parameters: + - name: id + in: path + description: The id of the IP whitelabel that you want to delete. + required: true + type: string + delete: + tags: + - Whitelabel - IPs + summary: Delete an IP whitelabel + description: |- + **This endpoint allows you to delete an IP whitelabel.** + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: DELETE_whitelabel-ips-id + consumes: [] + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: object + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The errors preventing the IP whitelabel from being deleted. + items: + type: object + properties: + message: + type: string + description: A message explaining why the IP whitelabel could not be deleted. + examples: + application/json: + errors: + - message: Whitelabel ip not found. + security: + - Authorization: [] + get: + tags: + - Whitelabel - IPs + summary: Retrieve an IP whitelabel + description: |- + **This endpoint allows you to retrieve an IP whitelabel.** + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: GET_whitelabel-ips-id + consumes: [] + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - type: object - properties: - ips: - type: array - items: - type: string - format: ipv4 + $ref: '#/definitions/ip_whitelabel' examples: application/json: - ips: - - 127.0.0.1 - '401': + id: 123 + ip: 192.168.1.1 + rdns: o1.email.example.com + users: + - username: john@example.com + user_id: 7 + subdomain: email + domain: example.com + valid: true + legacy: false + a_record: + valid: true + type: a + host: o1.email.example.com + data: 192.168.1.1 + '404': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + errors: + type: array + description: The errors preventing the retrieval of the IP whitelabel. + items: + type: object + properties: + message: + type: string + description: A message explaining why the IP whitelabel could not be found. + required: + - message + required: + - errors examples: application/json: errors: - - field: null - message: authorization required + - message: Whitelabel ip not found. + security: + - Authorization: [] /ips/assigned: parameters: [] get: @@ -10638,8 +8436,7 @@ paths: A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. operationId: GET_ips-assigned - consumes: - - application/json + consumes: [] produces: - application/json parameters: [] @@ -10680,24 +8477,23 @@ paths: start_date: 1409616000 security: - Authorization: [] - /geo/stats: + /devices/stats: parameters: [] get: tags: - Stats - Advanced Stats - summary: Retrieve email statistics by country and state/province. - description: |- - **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** - - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - operationId: GET_geo-stats - consumes: - - application/json + summary: Retrieve email statistics by device type. + description: "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html)." + operationId: GET_devices-stats + consumes: [] produces: - application/json parameters: + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string - name: limit in: query description: How many results to include on each page. @@ -10710,608 +8506,2318 @@ paths: type: integer - name: aggregated_by in: query - description: 'How you would like the statistics to be grouped. Must be either "day", "week", or "month".' + description: 'How to group the statistics. Must be either "day", "week", or "month".' required: false type: string - enum: - - day - - week - - month - name: start_date in: query - description: The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD + description: The starting date of the statistics to retrieve. required: true type: string - - name: end_date - in: query - description: 'The end date of the statistics to retrieve. ' - required: false - type: string - default: The date the request is made. - - name: country - in: query - description: The country you would like to see statistics for. Currently only supported for US and CA. - required: false - type: string - enum: - - US - - CA responses: '200': description: '' schema: type: array items: - $ref: '#/definitions/advanced_stats_country' + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - date: '2015-10-11' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-12' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-13' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-14' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-15' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-16' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-17' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-18' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-19' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-20' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-21' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 1 - unique_clicks: 0 unique_opens: 1 - date: '2015-10-22' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-23' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-24' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-25' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-26' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 + opens: 2 + unique_opens: 2 - date: '2015-10-27' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-28' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-29' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-30' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-10-31' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-01' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-02' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-03' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-04' - stats: - - type: province - name: TX + stats: + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-05' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-06' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-07' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-08' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-09' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - date: '2015-11-10' stats: - - type: province - name: TX + - type: device + name: Webmail metrics: - clicks: 0 opens: 0 - unique_clicks: 0 unique_opens: 0 - /devices/stats: + security: + - Authorization: [] + '/whitelabel/domains/{id}/validate': + parameters: + - name: id + in: path + required: true + type: string + post: + tags: + - Whitelabel - Domains + summary: Validate a domain whitelabel. + description: |- + **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer |ID of the domain whitelabel to validate. | + operationId: POST_whitelabel-domains-id-validate + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + id: + type: integer + description: The ID of the domain whitelabel. + valid: + type: boolean + description: Indicates if this is a valid whitelabel. + validation_resuts: + type: object + description: 'The individual DNS records that are checked when validating, including the reason for any invalid DNS records.' + properties: + mail_cname: + type: object + description: The CNAME record for the domain whitelabel. + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + reason: + type: string + description: The reason this record is invalid. + dkim1: + type: object + description: A DNS record for this domain whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + dkim2: + type: object + description: A DNS record for this whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + spf: + type: object + description: The SPF record for the whitelabel. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + reason: + type: 'null' + examples: + application/json: + id: 1 + valid: true + validation_resuts: + mail_cname: + valid: false + reason: Expected your MX record to be "mx.sendgrid.net" but found "example.com". + dkim1: + valid: true + reason: null + dkim2: + valid: true + reason: null + spf: + valid: true + reason: null + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + description: A message explaining the reason for the error. + required: + - message + examples: + application/json: + errors: + - message: internal error getting TXT + security: + - Authorization: [] + /campaigns: + parameters: [] + post: + tags: + - Campaigns API + summary: Create a Campaign + description: |- + **This endpoint allows you to create a campaign.** + + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + + Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/campaign_request' + example: + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:

Check out our spring line!

+ plain_content: Check out our spring line! + responses: + '201': + description: '' + schema: + $ref: '#/definitions/campaign_response' + examples: + application/json: + id: 986724 + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:

Check out our spring line!

+ plain_content: Check out our spring line! + status: Draft + '400': + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." + "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: title + message: title can't be blank + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' + - field: null + message: The JSON you have submitted cannot be parsed. + - field: null + message: You've reached your limit of 250 campaigns. Please delete one or more and try again. + '401': + description: '' + schema: + type: object + security: + - Authorization: [] + get: + tags: + - Campaigns API + summary: Retrieve all Campaigns + description: |- + **This endpoint allows you to retrieve a list of all of your campaigns.** + + Returns campaigns in reverse order they were created (newest first). + + Returns an empty array if no campaigns exist. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: GET_campaigns + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of results you would like to receive at a time. + type: integer + default: 10 + - name: offset + in: query + description: 'The index of the first campaign to return, where 0 is the first campaign.' + type: integer + default: 0 + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + type: object + properties: + categories: + type: array + items: + type: string + custom_unsubscribe_url: + type: string + html_content: + type: string + id: + type: integer + ip_pool: + type: string + list_ids: + type: array + items: + type: integer + plain_content: + type: string + segment_ids: + type: array + items: + type: integer + sender_id: + type: integer + status: + type: string + subject: + type: string + suppression_group_id: + type: integer + title: + type: string + examples: + application/json: + result: + - categories: + - spring line + custom_unsubscribe_url: '' + html_content:

Check out our spring line!

+ id: 986724 + ip_pool: marketing + list_ids: + - 110 + plain_content: Check out our spring line! + segment_ids: + - 110 + sender_id: 124451 + status: Draft + subject: New Products for Spring! + suppression_group_id: 42 + title: March Newsletter + security: + - Authorization: [] + '/campaigns/{campaign_id}/schedules/now': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + summary: Send a Campaign + description: |- + **This endpoint allows you to immediately send a campaign at the time you make the API call.** + + Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns-campaign_id-schedules-now + consumes: [] + produces: + - application/json + parameters: [] + responses: + '201': + description: '' + schema: + title: Send a Campaign response + type: object + properties: + id: + type: integer + format: int64 + status: + type: string + required: + - id + - status + examples: + application/json: + id: 1234 + status: Scheduled + '400': + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: subject + message: subject can't be blank + - field: sender_id + message: sender_id can't be blank + - field: plain_content + message: 'plain_content can''t be blank, please provide plain text or html content' + - field: list_id + message: You must select at least 1 segment or 1 list to send to. + - field: unsubscribe_tag + message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' + - field: suppression_group_id + message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '403': + description: '"": "You may only send a campaign when it is in draft mode."' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: You may only send a campaign when it is in draft mode. + '404': + description: '"": "not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: not found + security: + - Authorization: [] + /whitelabel/domains: + parameters: [] + post: + tags: + - Whitelabel - Domains + summary: Create a domain whitelabel. + description: |- + **This endpoint allows you to create a whitelabel for one of your domains.** + + If you are creating a domain whitelabel that you would like a subuser to use, you have two options: + 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. + 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: POST_whitelabel-domains + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + domain: + type: string + description: Domain being whitelabeled. + subdomain: + type: string + description: The subdomain to use for this domain whitelabel. + username: + type: string + description: The username that this whitelabel will be associated with. + ips: + type: array + description: The IP addresses that will be included in the custom SPF record for this whitelabel. + items: + type: string + custom_spf: + type: boolean + description: Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security. + default: + type: boolean + description: Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain. + automatic_security: + type: boolean + description: 'Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.' + required: + - domain + - subdomain + example: + domain: example.com + subdomain: news + username: john@example.com + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + automatic_security: false + responses: + '201': + description: '' + schema: + $ref: '#/definitions/whitelabel::domain' + examples: + application/json: + id: 302183 + user_id: 1446226 + subdomain: example + domain: example.com + username: mbernier + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: cname + host: example.example.com + data: u1446226.wl.sendgrid.net + dkim1: + valid: false + type: cname + host: s1._domainkey.example.com + data: s1.domainkey.u1446226.wl.sendgrid.net + dkim2: + valid: false + type: cname + host: s2._domainkey.example.com + data: s2.domainkey.u1446226.wl.sendgrid.net + security: + - Authorization: [] + get: + tags: + - Whitelabel - Domains + summary: List all domain whitelabels. + description: | + **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: GET_whitelabel-domains + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + description: Number of domains to return. + type: integer + - name: offset + in: query + description: Paging offset. + type: integer + - name: exclude_subusers + in: query + description: Exclude subuser domains from the result. + type: boolean + - name: username + in: query + description: The username associated with a whitelabel. + type: string + - name: domain + in: query + description: Search for domain whitelabels that match the given domain. + type: string + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + id: + type: number + description: The ID of the domain whitelabel. + user_id: + type: number + description: The ID of the user that this whitelabel will be associated with. + subdomain: + type: string + description: The subdomain created for this domain whitelabel. + domain: + type: string + description: The domain that this whitelabel was created for. + username: + type: string + description: The username that this whitelabel is associated with. + ips: + type: array + description: The IPs that will be included in the custom SPF record. + items: + type: string + custom_spf: + type: boolean + description: Indicates if this whitelabel has custom SPF. + default: + type: boolean + description: Indicates if this whitelabel has been set as the default whitelabel. + legacy: + type: boolean + description: Indicates if this is whitelabel was created with the legacy whitelabel tool. + automatic_security: + type: boolean + description: Indicates if this whitelabel uses automated security. + valid: + type: boolean + description: Indicates if this is a valid whitelabel or not. + dns: + type: object + description: The DNS records for this whitelabel that are used for authenticating the sending domain. + properties: + mail_server: + type: object + description: Designates which mail server is responsible for accepting messages from a domain. + properties: + valid: + type: boolean + description: Indicates if this is a valid DNS record with no conflicts. + type: + type: string + description: The type of DNS record. + host: + type: string + description: The domain sending the messages. + data: + type: string + description: The mail server responsible for accepting messages. + subdomain_spf: + type: object + description: The SPF record for the subdomain used to create this whitelabel. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + type: + type: string + description: The type of data in the SPF record. + host: + type: string + description: The domain that this SPF record will be used to authenticate. + data: + type: string + description: The SPF record. + dkim: + type: object + description: The DNS record used when creating the DKIM signature. + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + type: + type: string + description: The type of DNS record. + enum: + - cname + - mx + - txt + host: + type: string + description: The domain that these DNS records will be applied to. + format: hostname + data: + type: string + description: The DNS record. + required: + - id + - user_id + - subdomain + - domain + - username + - ips + - custom_spf + - default + - legacy + - automatic_security + - valid + - dns + examples: + application/json: + - id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + legacy: false + automatic_security: true + valid: true + dns: + mail_cname: + host: mail.example.com + type: cname + data: u7.wl.sendgrid.net + valid: true + spf: + host: example.com + type: txt + data: 'v=spf1 include:u7.wl.sendgrid.net -all' + valid: true + dkim1: + host: s1._domainkey.example.com + type: cname + data: s1._domainkey.u7.wl.sendgrid.net + valid: true + dkim2: + host: s2._domainkey.example.com + type: cname + data: s2._domainkey.u7.wl.sendgrid.net + valid: true + - id: 2 + domain: example2.com + subdomain: news + username: jane@example2.com + user_id: 8 + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_server: + host: news.example2.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: news.example2.com + type: txt + data: 'v=spf1 include:sendgrid.net ~all' + valid: false + domain_spf: + host: example2.com + type: txt + data: 'v=spf1 include:news.example2.com -all' + valid: false + dkim: + host: example2.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false + security: + - Authorization: [] + '/whitelabel/links/{id}/validate': + parameters: + - name: id + in: path + description: The id of the link whitelabel that you want to validate. + required: true + type: integer + post: + tags: + - Whitelabel - Links + summary: Validate a Link Whitelabel + description: |- + **This endpoint allows you to validate a link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: POST_whitelabel-links-id-validate + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + id: + type: integer + description: The id of the link whitelabel. + valid: + type: boolean + description: Indicates if the link whitelabel is valid. + enum: + - true + - false + validation_results: + type: object + description: The individual validations results for each of the DNS records associated with this link whitelabel. + required: + - domain_cname + properties: + domain_cname: + type: object + description: The DNS record generated for the sending domain used for this link whitelabel. + required: + - valid + - reason + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + enum: + - true + - false + reason: + type: + - string + - 'null' + description: 'Null if the DNS record is valid. If the DNS record is invalid, this will explain why.' + owner_cname: + type: object + description: The DNS record created to verify the link whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: 'Null if valid. If the DNS record is invalid, this will explain why.' + required: + - valid + - reason + required: + - id + - valid + - validation_results + examples: + application/json: + id: 1 + valid: true + validation_results: + domain_cname: + valid: false + reason: Expected CNAME to match "sendgrid.net." but found "example.com.". + owner_cname: + valid: true + reason: null + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The reasons why the validation failed. + items: + type: object + properties: + message: + type: string + description: The reason why the link whitelabel could not be validated. + required: + - message + required: + - errors + examples: + application/json: + errors: + - message: internal error getting CNAME + security: + - Authorization: [] + '/whitelabel/ips/{id}/validate': + parameters: + - name: id + in: path + required: true + type: integer + post: + tags: + - Whitelabel - IPs + summary: Validate an IP whitelabel + description: |- + **This endpoint allows you to validate an IP whitelabel.** + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: POST_whitelabel-ips-id-validate + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + id: + type: integer + description: The id of the IP whitelabel. + valid: + type: boolean + description: Indicates if the IP whitelabel is valid. + enum: + - true + - false + validation_results: + type: object + description: The specific results of the validation. + properties: + a_record: + type: object + properties: + valid: + type: boolean + description: Indicates if the IP whitelabel could be validated. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated. + required: + - valid + - reason + required: + - id + - valid + - validation_results + examples: + application/json: + id: 1 + valid: true + validation_results: + a_record: + valid: true + reason: null + '404': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object + properties: + errors: + type: array + description: The error messages for the failed validation. + items: + type: object + properties: + message: + type: string + description: A message describing why the IP could not be validated. + required: + - message + required: + - errors + examples: + application/json: + errors: + - message: Whitelabel ip not found. + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The error messages for the failed validation. + items: + type: object + properties: + message: + type: string + description: A message describing why the IP whitelabel could not be validated. + required: + - message + required: + - errors + examples: + application/json: + errors: + - message: internal error getting rDNS + security: + - Authorization: [] + /tracking_settings/subscription: + parameters: [] + patch: + summary: Update Subscription Tracking Settings + description: |- + **This endpoint allows you to update your current settings for subscription tracking.** + + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-subscription + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/subscription_tracking_settings' + example: + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content + responses: + '200': + description: '' + schema: + $ref: '#/definitions/subscription_tracking_settings' + examples: + application/json: + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content + security: + - Authorization: [] + get: + summary: Retrieve Subscription Tracking Settings + description: |- + **This endpoint allows you to retrieve your current settings for subscription tracking.** + + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-subscription + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/subscription_tracking_settings' + examples: + application/json: + enabled: true + html_content: | +

Something something unsubscribe <% %> something something

+ landing: | +

subscribehere

+ plain_content: Something something unsubscribe <% %> something something + replace: thetag + url: '' + security: + - Authorization: [] + /categories: + parameters: [] + get: + tags: + - Categories + summary: Retrieve all categories + description: |- + **This endpoint allows you to retrieve a list of all of your categories.** + + Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). + operationId: GET_categories + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of categories to display per page. + type: integer + default: 50 + - name: category + in: query + description: Allows you to perform a prefix search on this particular category. + type: string + - name: offset + in: query + description: The point in the list that you would like to begin displaying results. + type: integer + default: 0 + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + category: + type: string + description: A category used to group emails by broad topic. + required: + - category + examples: + application/json: + - category: category 1 + - category: category 2 + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The error returned. + items: + type: object + properties: + field: + type: string + message: + type: string + description: A message explaining why your categories could not be retrieved. + required: + - field + - message + examples: + application/json: + errors: + - field: sort_by + message: invalid sort value + security: + - Authorization: [] + /tracking_settings: + parameters: [] + get: + summary: Retrieve Tracking Settings + description: |- + **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of settings to return. + type: integer + - name: offset + in: query + description: Where in the list of results you want to begin retrieving settings. + type: integer + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + description: The list of all tracking settings. + items: + type: object + properties: + name: + type: string + description: The name of the event being tracked. + title: + type: string + description: The title of the tracking setting. + description: + type: string + description: A description about the event that is being tracked. + enabled: + type: boolean + description: Indicates if this tracking setting is currently enabled. + examples: + application/json: + result: + - name: open + title: Open Tracking + description: lorem ipsum... . + enabled: true + security: + - Authorization: [] + /tracking_settings/google_analytics: + parameters: [] + get: + summary: Retrieve Google Analytics Settings + description: |- + **This endpoint allows you to retrieve your current setting for Google Analytics.** + + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). + + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-google_analytics + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/google_analytics_settings' + examples: + application/json: + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' + security: + - Authorization: [] + patch: + summary: Update Google Analytics Settings + description: |- + **This endpoint allows you to update your current setting for Google Analytics.** + + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). + + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-google_analytics + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/google_analytics_settings' + example: + enabled: true + utm_source: sendgrid.com + utm_medium: email + utm_term: '' + utm_content: '' + utm_campaign: website + responses: + '200': + description: '' + schema: + $ref: '#/definitions/google_analytics_settings' + examples: + application/json: + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' + security: + - Authorization: [] + /tracking_settings/click: + parameters: [] + patch: + summary: Update Click Tracking Settings + description: |- + **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-click + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: The setting you want to use for click tracking. + example: + enabled: true + responses: + '200': + description: '' + schema: + type: object + properties: + enable_text: + type: boolean + description: Indicates if click tracking is enabled for plain text emails + enabled: + type: boolean + description: The new setting new setting for click tracking. + required: + - enable_text + - enabled + examples: + application/json: + enable_text: false + enabled: true + security: + - Authorization: [] + get: + summary: Retrieve Click Track Settings + description: |- + **This endpoint allows you to retrieve your current click tracking setting.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-click + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + enable_text: + type: boolean + description: Indicates if click tracking is enabled for plain text emails. + enabled: + type: boolean + description: Indicates if click tracking is enabled or disabled. + required: + - enable_text + - enabled + examples: + application/json: + enable_text: false + enabled: true + security: + - Authorization: [] + /tracking_settings/open: + parameters: [] + patch: + summary: Update Open Tracking Settings + description: |- + **This endpoint allows you to update your current settings for open tracking.** + + Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-open + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: The new status that you want to set for open tracking. + example: + enabled: true + responses: + '200': + description: '' + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if open tracking is enabled. + required: + - enabled + examples: + application/json: + enabled: true + security: + - Authorization: [] + get: + summary: Get Open Tracking Settings + description: |- + **This endpoint allows you to retrieve your current settings for open tracking.** + + Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-open + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if open tracking is enabled. + required: + - enabled + examples: + application/json: + enabled: true + security: + - Authorization: [] + /mail_settings: + parameters: [] + get: + summary: Retrieve all mail settings + description: |- + **This endpoint allows you to retrieve a list of all mail settings.** + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of settings to return. + type: integer + - name: offset + in: query + description: Where in the list of results to begin displaying settings. + type: integer + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + description: The list of all mail settings. + items: + type: object + properties: + title: + type: string + description: The title of the mail setting. + enabled: + type: boolean + description: Indicates if this mail setting is currently enabled. + name: + type: string + description: The name of the mail setting. + description: + type: string + description: A description of the mail setting. + required: + - title + - enabled + - name + - description + required: + - result + examples: + application/json: + result: + - title: Address Whitelist + enabled: false + name: address_whitelist + description: Address / domains that should never have email suppressed. + - title: BCC + enabled: false + name: bcc + description: Automatically BCC an address for every e-mail sent. + - title: Bounce Purge + enabled: false + name: bounce_purge + description: Allows you to automatically purge bounce records from SendGrid after a specified number of days. + - title: Event Notification + enabled: true + name: event_notify + description: 'Controls notifications for events, such as bounces, clicks, and opens.' + - title: Footer + enabled: false + name: footer + description: Allows you to add a custom footer to outgoing email. + - title: Forward Bounce + enabled: true + name: forward_bounce + description: Allows you to forward bounces to a specific email address. + - title: Forward Spam + enabled: false + name: forward_spam + description: Allows for a copy of spam reports to be forwarded to an email address. + - title: Legacy Email Template + enabled: true + name: template + description: Allows you to customize your outgoing HTML emails. + - title: Plain Content + enabled: false + name: plain_content + description: Convert your plain text emails to HTML. + - title: Spam Checker + enabled: true + name: spam_check + description: Check outbound messages for spam content. + security: + - Authorization: [] + /mail_settings/spam_check: + parameters: [] + patch: + summary: Update spam check mail settings + description: |- + **This endpoint allows you to update your current spam checker mail settings.** + + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-spam_check + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if you want the spam check mail setting to be enabled or not. + url: + type: string + description: The Inbound Parse URL where you would like your spam reports to be sent to. + max_score: + type: integer + default: 5 + description: 'The new max score, or spam threshold that you would like to set for the spam checker.' + minimum: 1 + maximum: 10 + example: + enabled: true + url: url + max_score: 5 + responses: + '200': + description: '' + schema: + $ref: '#/definitions/mail_settings_spam_check' + examples: + application/json: + enabled: false + max_score: 6 + url: 'http://example.com' + security: + - Authorization: [] + get: + summary: Retrieve spam check mail settings + description: |- + **This endpoint allows you to retrieve your current Spam Checker mail settings.** + + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-spam_check + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/mail_settings_spam_check' + examples: + application/json: + enabled: false + max_score: 6 + url: 'http://example.com' + security: + - Authorization: [] + /mail_settings/template: + parameters: [] + patch: + summary: Update template mail settings + description: |- + **This endpoint allows you to update your current legacy email template settings.** + + This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-template + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if you want to enable the legacy email template mail setting. + html_content: + type: string + description: The new HTML content for your legacy email template. + example: + enabled: true + html_content: <% body %> + responses: + '200': + description: '' + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if the legacy email template mail setting is enabled. + html_content: + type: string + description: The HTML content of your legacy email template. + required: + - enabled + - html_content + examples: + application/json: + enabled: false + html_content: | +

<% body %>Example

+ security: + - Authorization: [] + get: + summary: Retrieve legacy template mail settings + description: |- + **This endpoint allows you to retrieve your current legacy email template settings.** + + This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-template + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/mail_settings_template' + examples: + application/json: + enabled: false + html_content: | +

<% body %>Example

+ security: + - Authorization: [] + '/ips/pools/{pool_name}': + parameters: + - name: pool_name + in: path + description: The name of the IP pool that you want to retrieve the IP addresses from. + required: true + type: string + get: + summary: Retrieve all IPs in a specified pool. + description: |- + **This endpoint allows you to list all of the IP addresses that are in a specific IP pool.** + + IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + + IP pools can only be used with whitelabeled IP addresses. + + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: GET_ips-pools-pool_name + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + pool_name: + type: string + description: The name of the IP pool. + maxLength: 64 + ips: + type: array + description: The list of IP addresses that belong to this IP pool. + items: + type: string + required: + - pool_name + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + description: The name of the error. + message: + type: string + description: A message explaining why the IP addresses could not be listed. + examples: + application/json: + errors: + - field: error + message: Unable to locate specified IPs Pool + security: + - Authorization: [] + delete: + summary: Delete an IP pool. + description: |- + **This endpoint allows you to delete an IP pool.** + + IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + + IP pools can only be used with whitelabeled IP addresses. + + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: DELETE_ips-pools-pool_name + consumes: [] + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: object + '404': + description: '' + schema: + type: object + properties: + error: + type: string + description: An error explaining why the pool could not be deleted. + examples: + application/json: + error: Unable to locate specified IPs Pool + security: + - Authorization: [] + put: + summary: Update an IP pool’s name. + description: |- + **This endpoint allows you to update the name of an IP pool.** + + IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + + IP pools can only be used with whitelabeled IP addresses. + + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: PUT_ips-pools-pool_name + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The new name for your IP pool. + maxLength: 64 + example: + name: new_pool_name + responses: + '200': + description: '' + schema: + $ref: '#/definitions/ip_pool' + examples: + application/json: + name: new_pool_name + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the name of your IP pool could not be updated. + examples: + application/json: + errors: + - field: null + message: ip pool not found + security: + - Authorization: [] + /ips: parameters: [] get: tags: - - Stats - Advanced Stats - summary: Retrieve email statistics by device type. - description: "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html)." - operationId: GET_devices-stats - consumes: - - application/json + - IP Addresses + summary: Retrieve all IP addresses + description: |- + **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** + + Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. + + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + operationId: GET_ips + consumes: [] produces: - application/json parameters: - - name: end_date + - name: ip in: query - description: The end date of the statistics to retrieve. Defaults to today. - required: false + description: The IP address to get + type: string + - name: exclude_whitelabels + in: query + description: Should we exclude whitelabels? + type: boolean + - name: subuser + in: query + description: The subuser you are requesting for. type: string - name: limit in: query - description: How many results to include on each page. - required: false + description: The number of IPs you want returned at the same time. type: integer + default: 10 - name: offset in: query - description: How many results to exclude. - required: false + description: The offset for the number of IPs that you are requesting. type: integer - - name: aggregated_by + default: 0 + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + ip: + type: string + description: An IP address. + subusers: + type: array + description: The subusers that are able to send email from this IP. + items: + type: string + rdns: + type: string + description: The reverse DNS record for this IP address. + pools: + type: array + description: The IP pools that this IP has been added to. + items: + type: string + warmup: + type: boolean + description: Indicates if this IP address is currently warming up. + start_date: + type: + - number + - 'null' + description: The date that the IP address was entered into warmup. + whitelabeled: + type: boolean + description: Indicates if this IP address has been whitelabeled. + required: + - ip + - subusers + - pools + - warmup + - start_date + - whitelabeled + examples: + application/json: + - ip: 127.0.0.1 + subusers: + - example_subuser1 + - example_subuser2 + rdns: o1.em.example.com + pools: [] + warmup: true + start_date: 1250337600 + whitelabeled: true + - ip: 127.0.0.1 + subusers: [] + pools: [] + warmup: false + start_date: null + whitelabeled: false + security: + - Authorization: [] + '/ips/warmup/{ip_address}': + parameters: + - name: ip_address + in: path + description: The IP address that you want to remove from warmup mode. + required: true + type: string + delete: + summary: Remove an IP from warmup + description: |- + **This endpoint allows you to remove an IP address from warmup mode.** + + SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + + For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). + operationId: DELETE_ips-warmup-ip_address + consumes: [] + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: object + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The errors that were encountered. + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the IP couldn't be removed from warmup. + examples: + application/json: + errors: + - field: null + message: resource not found + security: + - Authorization: [] + get: + summary: Retrieve warmup status for a specific IP address + description: |- + **This endpoint allows you to retrieve the warmup status for a specific IP address.** + + SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + + For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). + operationId: GET_ips-warmup-ip_address + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/ip_warmup_response' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The errors that were encountered. + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the warmup status could not be retrieved. + examples: + application/json: + errors: + - field: null + message: resource not found + security: + - Authorization: [] + /suppression/unsubscribes: + parameters: [] + get: + tags: + - Suppression Management - Global Suppressions + summary: Retrieve all global suppressions + description: |- + **This endpoint allows you to retrieve a list of all email address that are globally suppressed.** + + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: GET_suppression-unsubscribes + consumes: [] + produces: + - application/json + parameters: + - name: start_time in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - - name: start_date + description: Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive). + type: integer + - name: limit + in: query + description: The number of results to display on each page. + type: integer + - name: offset in: query - description: The starting date of the statistics to retrieve. - required: true - type: string + description: The point in the list of results to begin displaying global suppressions. + type: integer responses: '200': description: '' schema: type: array items: - $ref: '#/definitions/advanced_stats_opens' + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the recipient was added to the global suppression list. + email: + type: string + description: The email address of the recipient who is globally suppressed. + required: + - created + - email examples: application/json: - - date: '2015-10-11' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-12' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-13' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-14' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-15' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-16' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-17' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-18' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-19' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-20' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-21' - stats: - - type: device - name: Webmail - metrics: - opens: 1 - unique_opens: 1 - - date: '2015-10-22' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-23' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-24' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-25' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-26' - stats: - - type: device - name: Webmail - metrics: - opens: 2 - unique_opens: 2 - - date: '2015-10-27' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-28' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-29' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-30' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-31' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-01' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-02' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-03' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-04' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-05' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-06' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-07' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-08' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-09' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-10' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 + - created: 1443651141 + email: user1@example.com + - created: 1443651154 + email: user2@example.com security: - Authorization: [] - '/whitelabel/domains/{id}/validate': - parameters: - - name: id - in: path - required: true - type: string + /asm/suppressions/global: + parameters: [] post: - tags: - - Whitelabel - Domains - summary: Validate a domain whitelabel. - description: |- - **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + tags: + - Suppression Management - Global Suppressions + summary: Add recipient addresses to the global suppression group. + description: |- + **This endpoint allows you to add one or more email addresses to the global suppressions group.** - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer |ID of the domain whitelabel to validate. | - operationId: POST_whitelabel-domains-id-validate + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: POST_asm-suppressions-global consumes: - application/json produces: @@ -11320,339 +10826,386 @@ paths: - name: body in: body schema: - type: 'null' + type: object + properties: + recipient_emails: + type: array + description: 'The email address, or addresses, that you want to add to the global suppressions group.' + items: + type: string + example: + recipient_emails: + - test1@example.com + - test2@example.com responses: - '200': + '201': description: '' schema: type: object properties: - id: - type: integer - description: The ID of the domain whitelabel. - valid: - type: boolean - description: Indicates if this is a valid whitelabel. - validation_resuts: - type: object - description: 'The individual DNS records that are checked when validating, including the reason for any invalid DNS records.' - properties: - mail_cname: - type: object - description: The CNAME record for the domain whitelabel. - properties: - valid: - type: boolean - description: Indicates if this DNS record is valid. - reason: - type: string - description: The reason this record is invalid. - dkim1: - type: object - description: A DNS record for this domain whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - reason: - type: 'null' - dkim2: - type: object - description: A DNS record for this whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - reason: - type: 'null' - spf: - type: object - description: The SPF record for the whitelabel. - properties: - valid: - type: boolean - description: Indicates if the SPF record is valid. - reason: - type: 'null' + recipient_emails: + type: array + description: The email addresses that are globally suppressed + items: + type: string + required: + - recipient_emails examples: application/json: - id: 1 - valid: true - validation_resuts: - mail_cname: - valid: false - reason: Expected your MX record to be "mx.sendgrid.net" but found "example.com". - dkim1: - valid: true - reason: null - dkim2: - valid: true - reason: null - spf: - valid: true - reason: null - '400': - description: Unexpected error in API call. See HTTP response body for details. + recipient_emails: + - test1@example.com + - test2@example.com + security: + - Authorization: [] + '/asm/suppressions/global/{email}': + parameters: + - name: email + in: path + description: 'The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.' + required: true + type: string + get: + tags: + - Suppression Management - Global Suppressions + summary: Retrieve a Global Suppression + description: |- + **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** + + If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned. + + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: GET_asm-suppressions-global-email + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' schema: + title: Retrieve a Global Suppression response type: object - '500': + properties: + recipient_email: + type: string + description: The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed. + required: + - recipient_email + security: + - Authorization: [] + delete: + tags: + - Suppression Management - Global Suppressions + summary: Delete a Global Suppression + description: |- + **This endpoint allows you to remove an email address from the global suppressions group.** + + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: DELETE_asm-suppressions-global-email + consumes: [] + produces: [] + parameters: [] + responses: + '204': description: '' + security: + - Authorization: [] + /suppression/invalid_emails: + parameters: [] + delete: + summary: Delete invalid emails + description: |- + **This endpoint allows you to remove email addresses from your invalid email address list.** + + There are two options for deleting invalid email addresses: + + 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. + 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. + + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: DELETE_suppression-invalid_emails + consumes: + - application/json + produces: [] + parameters: + - name: body + in: body schema: type: object properties: - errors: + delete_all: + type: boolean + description: Indicates if you want to remove all email address from the invalid emails list. + emails: type: array + description: The list of specific email addresses that you want to remove. items: - type: object - properties: - message: - type: string - description: A message explaining the reason for the error. - required: - - message + type: string + example: + delete_all: false + emails: + - example1@example.com + - example2@example.com + responses: + '204': + description: '' + security: + - Authorization: [] + get: + summary: Retrieve all invalid emails + description: |- + **This endpoint allows you to retrieve a list of all invalid email addresses.** + + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: GET_suppression-invalid_emails + consumes: [] + produces: + - application/json + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when an invalid email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when an invalid email was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: Paging offset. The point in the list to begin displaying results. + type: integer + responses: + '200': + description: '' + schema: + type: array + description: The list of invalid email addresses. + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the invalid emails list. + email: + type: string + description: The email address that was marked as invalid. + reason: + type: string + description: The reason that the email address was marked as invalid. + required: + - created + - email + - reason examples: application/json: - errors: - - message: internal error getting TXT + - created: 1449953655 + email: user1@example.com + reason: Mail domain mentioned in email address is unknown + - created: 1449939373 + email: user1@example.com + reason: Mail domain mentioned in email address is unknown security: - Authorization: [] - '/campaigns/{campaign_id}/schedules/now': + '/suppression/invalid_emails/{email}': parameters: - - name: campaign_id + - name: email in: path + description: The specific email address of the invalid email entry that you want to retrieve. required: true - type: integer - post: - summary: Send a Campaign + type: string + get: + summary: Retrieve a specific invalid email description: |- - **This endpoint allows you to immediately send a campaign at the time you make the API call.** + **This endpoint allows you to retrieve a specific invalid email addresses.** - Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - For more information: + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns-campaign_id-schedules-now - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: GET_suppression-invalid_emails-email + consumes: [] produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: - '201': + '200': description: '' schema: - title: Send a Campaign response - type: object - properties: - id: - type: integer - format: int64 - status: - type: string - required: - - id - - status - examples: - application/json: - id: 1234 - status: Scheduled - '400': - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the invalid emails list. + email: + type: string + description: The email address that was marked as invalid. + reason: + type: string + description: A reason explaining why the email address was marked as invalid. + required: + - created + - email + - reason examples: application/json: - errors: - - field: subject - message: subject can't be blank - - field: sender_id - message: sender_id can't be blank - - field: plain_content - message: 'plain_content can''t be blank, please provide plain text or html content' - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '401': + - created: 1454433146 + email: test1@example.com + reason: Mail domain mentioned in email address is unknown + delete: + summary: Delete a specific invalid email + description: |- + **This endpoint allows you to remove a specific email address from the invalid email address list.** + + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: DELETE_suppression-invalid_emails-email + consumes: [] + produces: [] + parameters: [] + responses: + '204': + description: '' + /suppression/spam_reports: + parameters: [] + get: + summary: Retrieve all spam reports + description: |- + **This endpoint allows you to retrieve all spam reports.** + + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: GET_suppression-spam_reports + consumes: [] + produces: + - application/json + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when a spam report was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when a spam report was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: Paging offset. The point in the list to begin displaying results. + type: integer + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You may only send a campaign when it is in draft mode."' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: You may only send a campaign when it is in draft mode. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the spam report was made. + email: + type: string + description: The email address of the recipient who marked your message as spam. + ip: + type: string + description: The IP address that the message was sent on. + required: + - created + - email + - ip examples: application/json: - errors: - - field: null - message: not found + - created: 1443651141 + email: user1@example.com + ip: 10.63.202.100 + - created: 1443651154 + email: user2@example.com + ip: 10.63.202.100 security: - Authorization: [] - /whitelabel/domains: - parameters: [] - post: - tags: - - Whitelabel - Domains - summary: Create a domain whitelabel. + delete: + summary: Delete spam reports description: |- - **This endpoint allows you to create a whitelabel for one of your domains.** + **This endpoint allows you to delete your spam reports.** - If you are creating a domain whitelabel that you would like a subuser to use, you have two options: - 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. - 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. + There are two options for deleting spam reports: - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + 1) You can delete all spam reports by setting "delete_all" to true in the request body. + 2) You can delete some spam reports by specifying the email addresses in an array in the request body. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - operationId: POST_whitelabel-domains + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: DELETE_suppression-spam_reports consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: type: object properties: - domain: - type: string - description: Domain being whitelabeled. - subdomain: - type: string - description: The subdomain to use for this domain whitelabel. - username: - type: string - description: The username that this whitelabel will be associated with. - ips: + delete_all: + type: boolean + description: Indicates if you want to delete all email addresses on the spam report list. + emails: type: array - description: The IP addresses that will be included in the custom SPF record for this whitelabel. + description: A list of specific email addresses that you want to remove from the spam report list. items: type: string - custom_spf: - type: boolean - description: Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security. - default: - type: boolean - description: Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain. - automatic_security: - type: boolean - description: 'Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.' - required: - - domain - - subdomain example: - domain: example.com - subdomain: news - username: john@example.com - ips: - - 192.168.1.1 - - 192.168.1.2 - custom_spf: true - default: true - automatic_security: false + delete_all: false + emails: + - example1@example.com + - example2@example.com responses: - '201': + '204': description: '' - schema: - $ref: '#/definitions/whitelabel::domain' - examples: - application/json: - id: 302183 - user_id: 1446226 - subdomain: example - domain: example.com - username: mbernier - ips: [] - custom_spf: false - default: true - legacy: false - automatic_security: true - valid: false - dns: - mail_cname: - valid: false - type: cname - host: example.example.com - data: u1446226.wl.sendgrid.net - dkim1: - valid: false - type: cname - host: s1._domainkey.example.com - data: s1.domainkey.u1446226.wl.sendgrid.net - dkim2: - valid: false - type: cname - host: s2._domainkey.example.com - data: s2.domainkey.u1446226.wl.sendgrid.net security: - Authorization: [] + '/suppression/spam_report/{email}': + parameters: + - name: email + in: path + description: The email address of a specific spam report that you want to retrieve. + required: true + type: string get: - tags: - - Whitelabel - Domains - summary: List all domain whitelabels. - description: | - **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** + summary: Retrieve a specific spam report + description: |- + **This endpoint allows you to retrieve a specific spam report.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - operationId: GET_whitelabel-domains - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: GET_suppression-spam_report-email + consumes: [] produces: - application/json - parameters: - - name: limit - in: query - description: Number of domains to return. - type: integer - - name: offset - in: query - description: Paging offset. - type: integer - - name: exclude_subusers - in: query - description: Exclude subuser domains from the result. - type: boolean - - name: username - in: query - description: The username associated with a whitelabel. - type: string - - name: domain - in: query - description: Search for domain whitelabels that match the given domain. - type: string + parameters: [] responses: '200': description: '' @@ -11661,362 +11214,206 @@ paths: items: type: object properties: - id: - type: number - description: The ID of the domain whitelabel. - user_id: - type: number - description: The ID of the user that this whitelabel will be associated with. - subdomain: - type: string - description: The subdomain created for this domain whitelabel. - domain: + created: + type: integer + description: A Unix timestamp that indicates when the recipient marked your message as spam. + email: type: string - description: The domain that this whitelabel was created for. - username: + description: The email address of the recipient that marked your message as spam. + ip: type: string - description: The username that this whitelabel is associated with. - ips: - type: array - description: The IPs that will be included in the custom SPF record. - items: - type: string - custom_spf: - type: boolean - description: Indicates if this whitelabel has custom SPF. - default: - type: boolean - description: Indicates if this whitelabel has been set as the default whitelabel. - legacy: - type: boolean - description: Indicates if this is whitelabel was created with the legacy whitelabel tool. - automatic_security: - type: boolean - description: Indicates if this whitelabel uses automated security. - valid: - type: boolean - description: Indicates if this is a valid whitelabel or not. - dns: - type: object - description: The DNS records for this whitelabel that are used for authenticating the sending domain. - properties: - mail_server: - type: object - description: Designates which mail server is responsible for accepting messages from a domain. - properties: - valid: - type: boolean - description: Indicates if this is a valid DNS record with no conflicts. - type: - type: string - description: The type of DNS record. - host: - type: string - description: The domain sending the messages. - data: - type: string - description: The mail server responsible for accepting messages. - subdomain_spf: - type: object - description: The SPF record for the subdomain used to create this whitelabel. - properties: - valid: - type: boolean - description: Indicates if the SPF record is valid. - type: - type: string - description: The type of data in the SPF record. - host: - type: string - description: The domain that this SPF record will be used to authenticate. - data: - type: string - description: The SPF record. - dkim: - type: object - description: The DNS record used when creating the DKIM signature. - properties: - valid: - type: boolean - description: Indicates if this DNS record is valid. - type: - type: string - description: The type of DNS record. - enum: - - cname - - mx - - txt - host: - type: string - description: The domain that these DNS records will be applied to. - format: hostname - data: - type: string - description: The DNS record. + description: The IP address that the message was sent from. required: - - id - - user_id - - subdomain - - domain - - username - - ips - - custom_spf - - default - - legacy - - automatic_security - - valid - - dns + - created + - email + - ip examples: application/json: - - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - ips: - - 192.168.1.1 - - 192.168.1.2 - custom_spf: true - default: true - legacy: false - automatic_security: true - valid: true - dns: - mail_cname: - host: mail.example.com - type: cname - data: u7.wl.sendgrid.net - valid: true - spf: - host: example.com - type: txt - data: 'v=spf1 include:u7.wl.sendgrid.net -all' - valid: true - dkim1: - host: s1._domainkey.example.com - type: cname - data: s1._domainkey.u7.wl.sendgrid.net - valid: true - dkim2: - host: s2._domainkey.example.com - type: cname - data: s2._domainkey.u7.wl.sendgrid.net - valid: true - - id: 2 - domain: example2.com - subdomain: news - username: jane@example2.com - user_id: 8 - ips: [] - custom_spf: false - default: true - legacy: false - automatic_security: true - valid: false - dns: - mail_server: - host: news.example2.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: news.example2.com - type: txt - data: 'v=spf1 include:sendgrid.net ~all' - valid: false - domain_spf: - host: example2.com - type: txt - data: 'v=spf1 include:news.example2.com -all' - valid: false - dkim: - host: example2.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false + - created: 1454433146 + email: test1@example.com + ip: 10.89.32.5 security: - Authorization: [] - '/clients/{client_type}/stats': - parameters: - - name: client_type - in: path - description: 'Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".' - required: true - type: string - enum: - - phone - - tablet - - webmail - - desktop - get: - summary: Retrieve stats by a specific client type. + delete: + summary: Delete a specific spam report description: |- - **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** + **This endpoint allows you to delete a specific spam report.** - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - ## Available Client Types - - phone - - tablet - - webmail - - desktop + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: DELETE_suppression-spam_report-email + consumes: [] + produces: [] + parameters: [] + responses: + '204': + description: '' + security: + - Authorization: [] + /contactdb/recipients/count: + parameters: [] + get: + tags: + - Contacts API - Recipients + summary: Retrieve a Count of Recipients + description: |- + **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.** - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - operationId: GET_clients-client_type-stats - consumes: - - application/json + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: GET_contactdb-recipients-count + consumes: [] produces: - application/json - parameters: - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - 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 - type: string - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month + parameters: [] responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/advanced_stats_opens' + $ref: '#/definitions/contactdb_recipient_count' examples: application/json: - - date: '2014-10-01' - stats: - - metrics: - opens: 1 - unique_opens: 1 - name: Gmail - type: client - - date: '2014-10-02' - stats: - - metrics: - opens: 0 - unique_opens: 0 - name: Gmail - type: client + recipient_count: 1234 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required security: - Authorization: [] - /browsers/stats: - parameters: [] - get: - tags: - - Stats - Advanced Stats - summary: 'Retrieve email statistics by browser. ' + '/ips/pools/{pool_name}/ips': + parameters: + - name: pool_name + in: path + description: The name of the IP pool that you want to add an IP address to. + required: true + type: string + post: + summary: Add an IP address to a pool description: |- - **This endpoint allows you to retrieve your email statistics segmented by browser type.** + **This endpoint allows you to add an IP address to an IP pool.** - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - operationId: GET_browsers-stats + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + operationId: POST_ips-pools-pool_name-ips consumes: - application/json produces: - application/json parameters: - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - type: string - - name: end_date - in: query - description: The end date of the statistics to retrieve. Defaults to today. - required: false - type: string - - name: limit - in: query - description: The number of results to include on each page. - required: false - type: string - - name: offset - in: query - description: The number of results to exclude. - required: false - type: string - - name: aggregated_by - in: query - description: 'How to group the stats. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - - name: browsers - in: query - description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times. - required: false - type: string + - name: body + in: body + schema: + type: object + properties: + ip: + type: string + description: The IP address that you want to add to an IP pool. + example: + ip: 0.0.0.0 responses: - '200': + '201': description: '' schema: - type: array - items: - $ref: '#/definitions/advanced_stats_clicks' + type: object + properties: + ip: + type: string + description: The IP address. + pools: + type: array + description: The list of IP pools that this IP address has been added to. + items: + type: string + start_date: + type: integer + description: A unix timestamp indicating when the warmup process began for the IP address. + warmup: + type: boolean + description: Indicates if the IP address is in warmup. + required: + - ip + - pools + - start_date + - warmup examples: application/json: - - date: '2014-10-01' - stats: - - metrics: - clicks: 0 - unique_clicks: 0 - name: Chrome - type: browser - - metrics: - clicks: 1 - unique_clicks: 1 - name: Firefox - type: browser - - date: '2014-10-02' - stats: - - metrics: - clicks: 0 - unique_clicks: 0 - name: Chrome - type: browser - - metrics: - clicks: 1 - unique_clicks: 1 - name: Firefox - type: browser + ip: 000.00.00.0 + pools: + - test1 + start_date: 1409616000 + warmup: true + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The error returned. + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the IP address could not be added to the IP Pool. + examples: + application/json: + errors: + - field: null + message: resource not found + security: + - Authorization: [] + '/asm/groups/{group_id}/suppressions/{email}': + parameters: + - name: group_id + in: path + description: The id of the suppression group that you are removing an email address from. + required: true + type: string + - name: email + in: path + description: The email address that you want to remove from the suppression group. + required: true + type: string + delete: + summary: Delete a suppression from a suppression group + description: |- + **This endpoint allows you to remove a suppressed email address from the given suppression group.** + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: DELETE_asm-groups-group_id-suppressions-email + consumes: [] + produces: [] + parameters: [] + responses: + '204': + description: '' security: - Authorization: [] - '/whitelabel/links/{id}/validate': - parameters: - - name: id - in: path - description: The id of the link whitelabel that you want to validate. - required: true - type: integer + /mail/send: + parameters: [] post: tags: - - Whitelabel - Links - summary: Validate a Link Whitelabel + - Mail Send + summary: v3 Mail Send description: |- - **This endpoint allows you to validate a link whitelabel.** + This endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + * Top level parameters are referred to as "global". + * Individual fields within the personalizations array will override any other global, or “message level”, parameters that are defined outside of personalizations. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: POST_whitelabel-links-id-validate + For an overview of the v3 Mail Send endpoint, please visit our [v3 API Reference](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html) + + For more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html). + operationId: POST_mail-send consumes: - application/json produces: @@ -12024,552 +11421,1366 @@ paths: parameters: - name: body in: body - schema: - type: 'null' - responses: - '200': - description: '' schema: type: object properties: - id: + personalizations: + type: array + description: An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. + uniqueItems: false + maxItems: 1000 + items: + type: object + properties: + to: + type: array + description: 'An array of recipients. Each object within this array may contain the name, but must always contain the email, of a recipient.' + minItems: 1 + maxItems: 100 + items: + type: object + properties: + '': + $ref: '#/definitions/email_object' + cc: + type: array + description: 'An array of recipients who will receive a copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.' + maxItems: 100 + items: + type: object + properties: + '': + $ref: '#/definitions/email_object' + bcc: + type: array + description: 'An array of recipients who will receive a blind carbon copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.' + maxItems: 100 + items: + type: object + properties: + '': + $ref: '#/definitions/email_object' + subject: + type: string + description: 'The subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310' + minLength: 1 + headers: + type: object + description: 'A collection of JSON key/value pairs allowing you to specify specific handling instructions for your email. You may not overwrite the following headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC' + substitutions: + type: object + description: 'A collection of key/value pairs following the pattern "substitution_tag":"value to substitute". All are assumed to be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters.' + maxProperties: 10000 + custom_args: + type: object + description: 'Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. May not exceed 10,000 bytes.' + send_at: + type: integer + description: A unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden. + required: + - to + from: + type: object + description: An email object containing the email address and name of the sender. + properties: + '': + $ref: '#/definitions/email_object' + reply_to: + type: object + description: An email object containing the email address and name of the individual who should receive responses to your email. + properties: + '': + $ref: '#/definitions/email_object' + subject: + type: string + description: 'The global, or “message level”, subject of your email. This may be overridden by personalizations[x].subject.' + minLength: 1 + content: + type: array + description: 'An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one mime type. To include more than one mime type, simply add another object to the array containing the `type` and `value` parameters.' + items: + type: object + properties: + type: + type: string + description: 'The mime type of the content you are including in your email. For example, “text/plain” or “text/html”.' + minLength: 1 + value: + type: string + description: The actual content of the specified mime type that you are including in your email. + minLength: 1 + required: + - type + - value + attachments: + type: array + description: An array of objects in which you can specify any attachments you want to include. + items: + type: object + properties: + content: + type: string + description: The Base64 encoded content of the attachment. + minLength: 1 + type: + type: string + description: 'The mime type of the content you are attaching. For example, “text/plain” or “text/html”.' + minLength: 1 + filename: + type: string + description: The filename of the attachment. + disposition: + type: string + default: attachment + description: 'The content-disposition of the attachment specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file being displayed automatically within the message while “attachment” results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file).' + enum: + - inline + - attachment + content_id: + type: string + description: 'The content id for the attachment. This is used when the disposition is set to “inline” and the attachment is an image, allowing the file to be displayed within the body of your email.' + required: + - content + - filename + template_id: + type: string + description: 'The id of a template that you would like to use. If you use a template that contains a subject and content (either text or html), you do not need to specify those at the personalizations nor message level. ' + sections: + type: object + description: An object of key/value pairs that define block sections of code to be used as substitutions. + headers: + type: object + description: An object containing key/value pairs of header names and the value to substitute for them. You must ensure these are properly encoded if they contain unicode characters. Must not be one of the reserved headers. + categories: + type: array + description: 'An array of category names for this message. Each category name may not exceed 255 characters. ' + uniqueItems: true + maxItems: 10 + items: + type: string + maxLength: 255 + custom_args: + type: object + description: 'Values that are specific to the entire send that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by personalizations[x].custom_args if that parameter has been defined. Total custom args size may not exceed 10,000 bytes.' + send_at: type: integer - description: The id of the link whitelabel. - valid: - type: boolean - description: Indicates if the link whitelabel is valid. - enum: - - true - - false - validation_results: + description: 'A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the personalizations[x].send_at parameter. Scheduling more ta 72 hours in advance is forbidden.' + batch_id: + type: string + description: 'This ID represents a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch, and also enables you to cancel or pause the delivery of that batch. For more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send.html ' + asm: + type: object + description: An object allowing you to specify how to handle unsubscribes. + properties: + group_id: + type: integer + description: The unsubscribe group to associate with this email. + groups_to_display: + type: array + description: An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page. + maxItems: 25 + items: + type: integer + required: + - group_id + ip_pool_name: + type: string + description: The IP Pool that you would like to send this email from. + minLength: 2 + maxLength: 64 + mail_settings: + type: object + description: A collection of different mail settings that you can use to specify how you would like this email to be handled. + properties: + bcc: + type: object + description: This allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent. + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + email: + type: string + description: The email address that you would like to receive the BCC. + format: email + bypass_list_management: + type: object + description: Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email. + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + footer: + type: object + description: The default footer that you would like included on every email. + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + text: + type: string + description: The plain text content of your footer. + html: + type: string + description: The HTML content of your footer. + sandbox_mode: + type: object + description: This allows you to send a test email to ensure that your request body is valid and formatted correctly. + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + spam_check: + type: object + description: This allows you to test the content of your email for spam. + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + threshold: + type: integer + description: 'The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam.' + minimum: 1 + maximum: 10 + post_to_url: + type: string + description: An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to. + tracking_settings: type: object - description: The individual validations results for each of the DNS records associated with this link whitelabel. - required: - - domain_cname + description: Settings to determine how you would like to track the metrics of how your recipients interact with your email. properties: - domain_cname: + click_tracking: type: object - description: The DNS record generated for the sending domain used for this link whitelabel. - required: - - valid - - reason + description: Allows you to track whether a recipient clicked a link in your email. properties: - valid: + enable: type: boolean - description: Indicates if this DNS record is valid. - enum: - - true - - false - reason: - type: - - string - - 'null' - description: 'Null if the DNS record is valid. If the DNS record is invalid, this will explain why.' - owner_cname: + description: Indicates if this setting is enabled. + enable_text: + type: boolean + description: Indicates if this setting should be included in the text/plain portion of your email. + open_tracking: type: object - description: The DNS record created to verify the link whitelabel. + description: 'Allows you to track whether the email was opened or not, but including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.' properties: - valid: + enable: type: boolean - description: Indicates if the DNS record is valid. - enum: - - true - - false - reason: - type: - - 'null' - - string - description: 'Null if valid. If the DNS record is invalid, this will explain why.' - required: - - valid - - reason + description: Indicates if this setting is enabled. + substitution_tag: + type: string + description: Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel. + subscription_tracking: + type: object + description: 'Allows you to insert a subscription management link at the bottom of the text and html bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag.' + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + text: + type: string + description: 'Text to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>' + html: + type: string + description: 'HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>' + substitution_tag: + type: string + description: 'A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting.' + ganalytics: + type: object + description: Allows you to enable tracking provided by Google Analytics. + properties: + enable: + type: boolean + description: Indicates if this setting is enabled. + utm_source: + type: string + description: 'Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)' + utm_medium: + type: string + description: Name of the marketing medium. (e.g. Email) + utm_term: + type: string + description: "Used to identify any paid keywords.\t" + utm_content: + type: string + description: "Used to differentiate your campaign from advertisements.\t" + utm_campaign: + type: string + description: "The name of the campaign.\t" required: - - id - - valid - - validation_results - examples: - application/json: - id: 1 - valid: true - validation_results: - domain_cname: - valid: false - reason: Expected CNAME to match "sendgrid.net." but found "example.com.". - owner_cname: - valid: true - reason: null - '400': - description: Unexpected error in API call. See HTTP response body for details. + - personalizations + - from + - subject + - content + example: + personalizations: + - to: + - email: john.doe@example.com + name: John Doe + cc: + - email: jane.doe@example.com + name: Jane Doe + bcc: + - email: sam.doe@example.com + name: Sam Doe + subject: 'Hello, World!' + headers: + X-Accept-Language: en + X-Mailer: MyApp + substitutions: + id: substitutions + type: object + custom_args: + customerAccountNumber: '[CUSTOMER ACCOUNT NUMBER GOES HERE]' + activationAttempt: '1' + New Argument 1: New Value 1 + send_at: 1409348513 + from: + email: sam.smith@example.com + name: Sam Smith + reply_to: + email: sam.smith@example.com + name: Sam Smith + subject: 'Hello, World!' + content: + - type: text/html + value: '

Hello, world!

' + attachments: + - content: '[BASE64 encoded content block here]' + type: jpg + name: file1 + filename: file1.jpg + disposition: inline + content_id: ii_139db99fdb5c3704 + template_id: '[YOUR TEMPLATE ID GOES HERE]' + sections: + section: + ':sectionName1': section 1 text + ':sectionName2': section 2 text + headers: {} + categories: + - category1 + - category2 + custom_args: + customerAccountNumber: '[CUSTOMER ACCOUNT NUMBER GOES HERE]' + activationAttempt: '1' + New Argument 1: New Value 1 + send_at: 1409348513 + batch_id: '[YOUR BATCH ID GOES HERE]' + asm: + group_id: 1 + groups_to_display: + - 1 + - 2 + - 3 + ip_pool_name: '[YOUR POOL NAME GOES HERE]' + mail_settings: + bcc: + enable: true + email: ben.doe@example.com + bypass_list_management: + enable: true + footer: + enable: true + text: 'Thanks,/n The SendGrid Team' + html:

Thanks
The SendGrid Team

+ sandbox_mode: + enable: false + spam_check: + enable: true + threshold: 3 + post_to_url: 'http://example.com/compliance' + tracking_settings: + click_tracking: + enable: true + enable_text: true + open_tracking: + enable: true + substitution_tag: '%opentrack' + subscription_tracking: + enable: true + text: If you would like to unsubscribe and stop receiveing these emails <% click here %>. + html: If you would like to unsubscribe and stop receiving these emails <% clickhere %>. + substitution_tag: <%click here%> + ganalytics: + enable: true + utm_campaign: '[NAME OF YOUR REFERRER SOURCE]' + utm_medium: '[NAME OF YOUR MARKETING MEDIUM e.g. email]' + utm_term: '[IDENTIFY PAID KEYWORDS HERE]' + utm_content: '[USE THIS SPACE TO DIFFERENTIATE YOUR EMAIL FROM ADS]' + utm_name: '[NAME OF YOUR CAMPAIGN]' + responses: + '202': + description: '' schema: type: object - '500': + properties: {} + '400': description: '' schema: - type: object - properties: - errors: - type: array - description: The reasons why the validation failed. - items: - type: object - properties: - message: - type: string - description: The reason why the link whitelabel could not be validated. - required: - - message - required: - - errors - examples: - application/json: - errors: - - message: internal error getting CNAME + $ref: '#/definitions/errors' + '401': + description: '' + schema: + $ref: '#/definitions/errors' + '413': + description: '' + schema: + $ref: '#/definitions/errors' security: - Authorization: [] - '/whitelabel/ips/{id}/validate': + '/asm/suppressions/{email}': parameters: - - name: id + - name: email in: path + description: The email address that you want to search suppression groups for. required: true - type: integer - post: + type: string + get: tags: - - Whitelabel - IPs - summary: Validate an IP whitelabel + - Suppression Management - Suppressions + summary: Retrieve all suppression groups for an email address description: |- - **This endpoint allows you to validate an IP whitelabel.** - - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + **This endpoint returns the list of all groups that the given email address has been unsubscribed from.** - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: POST_whitelabel-ips-id-validate + Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). + operationId: GET_asm-suppressions-email consumes: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: '200': description: '' schema: type: object properties: - id: - type: integer - description: The id of the IP whitelabel. - valid: - type: boolean - description: Indicates if the IP whitelabel is valid. - enum: - - true - - false - validation_results: - type: object - description: The specific results of the validation. - properties: - a_record: - type: object - properties: - valid: - type: boolean - description: Indicates if the IP whitelabel could be validated. - enum: - - true - - false - reason: - type: - - 'null' - - string - description: The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated. - required: - - valid - - reason - required: - - id - - valid - - validation_results - examples: - application/json: - id: 1 - valid: true - validation_results: - a_record: - valid: true - reason: null - '404': - description: Unexpected error in API call. See HTTP response body for details. - schema: - type: object - properties: - errors: + suppressions: type: array - description: The error messages for the failed validation. + description: The array of suppression groups. items: type: object properties: - message: + description: type: string - description: A message describing why the IP could not be validated. + description: The description of the suppression group. + id: + type: integer + description: The id of the suppression group. + is_default: + type: boolean + description: Indicates if the suppression group is set as the default. + name: + type: string + description: The name of the suppression group. + suppressed: + type: boolean + description: Indicates if the given email address is suppressed for this group. required: - - message + - description + - id + - is_default + - name + - suppressed required: - - errors + - suppressions examples: application/json: - errors: - - message: Whitelabel ip not found. - '500': + suppressions: + - description: Optional description. + id: 1 + is_default: true + name: Weekly News + suppressed: true + - description: Some daily news. + id: 2 + is_default: true + name: Daily News + suppressed: true + - description: An old group. + id: 2 + is_default: false + name: Old News + suppressed: false + security: + - Authorization: [] + /asm/suppressions: + parameters: [] + get: + tags: + - Suppression Management - Suppressions + summary: Retrieve all suppressions + description: |- + **This endpoint allows you to retrieve a list of all suppressions.** + + Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). + operationId: GET_asm-suppressions + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': description: '' schema: - type: object - properties: - errors: - type: array - description: The error messages for the failed validation. - items: - type: object - properties: - message: - type: string - description: A message describing why the IP whitelabel could not be validated. - required: - - message - required: - - errors + type: array + items: + type: object + properties: + email: + type: string + description: The email address that was suppressed. + group_id: + type: integer + description: The id of the suppression group that this email address belongs to. + group_name: + type: string + description: The name of the suppression group that this email address belongs to. + created_at: + type: integer + description: A UNIX timestamp indicating when the suppression was created. + required: + - email + - group_id + - group_name + - created_at examples: application/json: - errors: - - message: internal error getting rDNS + - email: test1@example.com + group_id: 1 + group_name: Weekly News + created_at: 1410986704 + - email: test1@example.com + group_id: 2 + group_name: Daily News + created_at: 1411493671 + - email: test2@example.com + group_id: 2 + group_name: Daily News + created_at: 1411493671 security: - Authorization: [] - /user/webhooks/event/test: + /browsers/stats: parameters: [] - post: + get: tags: - - Webhooks - summary: 'Test Event Notification Settings ' + - Stats - Advanced Stats + summary: 'Retrieve email statistics by browser. ' description: |- - **This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** + **This endpoint allows you to retrieve your email statistics segmented by browser type.** - SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - operationId: POST_user-webhooks-event-test - consumes: + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_browsers-stats + consumes: [] + produces: - application/json - produces: [] parameters: - - name: body - in: body - schema: - type: object - properties: - url: - type: string - description: The URL where you would like the test notification to be sent. - example: - url: url + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string + - name: limit + in: query + description: The number of results to include on each page. + required: false + type: string + - name: offset + in: query + description: The number of results to exclude. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the stats. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: browsers + in: query + description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times. + required: false + type: string responses: - '204': + '200': description: '' schema: - type: object + type: array + items: + $ref: '#/definitions/advanced_stats_clicks' + examples: + application/json: + - date: '2014-10-01' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser + - date: '2014-10-02' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser security: - Authorization: [] - /ips/warmup: + /categories/stats: parameters: [] get: tags: - - IP Warmup - summary: Retrieve all IPs currently in warmup + - Stats - Category Stats + summary: Retrieve Email Statistics for Categories description: |- - **This endpoint allows you to retrieve all of your IP addresses that are currently warming up.** + **This endpoint allows you to retrieve all of your email statistics for each of your categories.** - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - operationId: GET_ips-warmup - consumes: - - application/json + Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). + operationId: GET_categories-stats + consumes: [] produces: - application/json - parameters: [] + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD + required: true + 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 + type: string + - name: categories + in: query + description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. + required: true + type: string + - name: limit + in: query + description: The number of results to include. + required: false + type: integer + default: 500 + maximum: 500 + - name: offset + in: query + description: The number of results to skip. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: '200': description: '' schema: - $ref: '#/definitions/ip_warmup_response' + type: array + items: + $ref: '#/definitions/category_stats' examples: application/json: - - ip: 0.0.0.0 - start_date: 1409616000 + - date: '2015-10-01' + stats: + - type: category + name: docs + 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 + - type: category + name: mattscategory + 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-11-01' + stats: + - type: category + name: docs + 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 + - type: category + name: mattscategory + 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 security: - Authorization: [] - post: - tags: - - IP Warmup - summary: Add an IP to warmup + '/clients/{client_type}/stats': + parameters: + - name: client_type + in: path + description: 'Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".' + required: true + type: string + enum: + - phone + - tablet + - webmail + - desktop + get: + summary: Retrieve stats by a specific client type. description: |- - **This endpoint allows you to enter an IP address into warmup mode.** + **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - operationId: POST_ips-warmup - consumes: - - application/json + ## Available Client Types + - phone + - tablet + - webmail + - desktop + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_clients-client_type-stats + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - type: object - properties: - ip: - type: string - description: The IP address that you want to begin warming up. - example: - ip: 0.0.0.0 + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + 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 + type: string + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: '200': description: '' schema: - $ref: '#/definitions/ip_warmup_response' - examples: - application/json: - - ip: 0.0.0.0 - start_date: 1409616000 - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The errors that were encountered. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the IP couldn't entered into warmup mode. + type: array + items: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - errors: - - field: null - message: resource not found + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client security: - Authorization: [] - /categories: + /contactdb/recipients/search: parameters: [] get: tags: - - Categories - summary: Retrieve all categories + - Contacts API - Recipients + summary: Retrieve recipients matching search criteria description: |- - **This endpoint allows you to retrieve a list of all of your categories.** + **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** - Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - operationId: GET_categories - consumes: - - application/json + field_name: + + * is a variable that is substituted for your actual custom field name from your recipient. + * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) + * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert + your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to + Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through + Mon, 02 Feb 2015 23:59:59 GMT. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: GET_contactdb-recipients-search + consumes: [] produces: - application/json parameters: - - name: limit - in: query - description: The number of categories to display per page. - type: integer - default: 50 - - name: category + - name: '{field_name}' in: query - description: Allows you to perform a prefix search on this particular category. type: string - - name: offset + - name: '%7Bfield_name%7D' in: query - description: The point in the list that you would like to begin displaying results. - type: integer - default: 0 + type: string responses: '200': description: '' schema: - type: array - items: - type: object - properties: - category: - type: string - description: A category used to group emails by broad topic. - required: - - category + type: object + properties: + recipients: + type: array + items: + $ref: '#/definitions/contactdb_recipient' examples: application/json: - - category: category 1 - - category: category 2 + recipients: + - created_at: 1422313607 + email: jones@example.com + first_name: null + id: YUBh + last_clicked: null + last_emailed: null + last_name: Jones + last_opened: null + updated_at: 1422313790 + custom_fields: + - id: 23 + name: pet + value: Fluffy + type: text '400': - description: '' + description: |- + "" : "Returned if no search params are specified" + "field" : "Returned if the provided field is invalid or does not exist" schema: - type: object - properties: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: errors: - type: array - description: The error returned. - items: - type: object - properties: - field: - type: string - message: - type: string - description: A message explaining why your categories could not be retrieved. - required: - - field - - message + - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' + - message: No search params are specified + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: sort_by - message: invalid sort value + - field: null + message: authorization required security: - Authorization: [] - /user/webhooks/parse/settings: - parameters: [] + '/contactdb/segments/{segment_id}/recipients': + parameters: + - name: segment_id + in: path + description: The ID of the segment from which you want to retrieve recipients. + required: true + type: integer get: - tags: - - Webhooks - summary: Retrieve Parse Webhook settings + summary: Retrieve recipients on a segment description: |- - **This endpoint allows you to retrieve your current inbound parse webhook settings.** + **This endpoint allows you to retrieve all of the recipients in a segment with the given ID.** - SendGrid can parse the attachments and contents of incoming emails. The Parse API will POST the parsed email to a URL that you specify. For more information, see our Inbound [Parse Webhook documentation](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). - operationId: GET_user-webhooks-parse-settings - consumes: - - application/json + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: GET_contactdb-segments-segment_id-recipients + consumes: [] produces: - application/json - parameters: [] + parameters: + - name: page + in: query + type: integer + - name: page_size + in: query + type: integer responses: '200': description: '' schema: + title: List Recipients On a Segment response type: object - required: - - result properties: - result: + recipients: type: array - description: The array containing the parse webhook settings. items: - type: object - properties: - hostname: - type: string - description: The hostname of the URL where you would like your parsed emails to be posted. - url: - type: string - description: The URL where you want your parsed emails to be posted. - spam_check: - type: boolean - description: Indicates if the parsed content will be checked for spam. - send_raw: - type: boolean - description: Indicates if the raw content that was parsed will be posted. - required: - - hostname - - url - - spam_check - - send_raw + $ref: '#/definitions/contactdb_recipient' + required: + - recipients examples: application/json: - result: - - hostname: example.com - url: 'http://example.com/example' - spam_check: false - send_raw: false + recipients: + - created_at: 1422313607 + email: jones@example.com + first_name: null + id: YUBh + last_clicked: null + last_emailed: null + last_name: Jones + last_opened: null + updated_at: 1422313790 + custom_fields: + - id: 23 + name: pet + value: Indiana + type: text + '400': + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + schema: + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: |- + "segment_id" : "Returned if segment_id is not valid" + "segment_id" : "Returned if segment_id does not exist" + schema: + type: object security: - Authorization: [] - /tracking_settings: + /geo/stats: parameters: [] get: - summary: Retrieve Tracking Settings + tags: + - Stats - Advanced Stats + summary: Retrieve email statistics by country and state/province. description: |- - **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** + **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: GET_tracking_settings - consumes: - - application/json + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_geo-stats + consumes: [] produces: - application/json parameters: - name: limit in: query - description: The number of settings to return. + description: How many results to include on each page. + required: false type: integer - name: offset in: query - description: Where in the list of results you want to begin retrieving settings. + description: How many results to exclude. + required: false type: integer + - name: aggregated_by + in: query + description: 'How you would like the statistics to be grouped. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: 'The end date of the statistics to retrieve. ' + required: false + type: string + default: The date the request is made. + - name: country + in: query + description: The country you would like to see statistics for. Currently only supported for US and CA. + required: false + type: string + enum: + - US + - CA responses: '200': description: '' schema: - type: object - properties: - result: - type: array - description: The list of all tracking settings. - items: - type: object - properties: - name: - type: string - description: The name of the event being tracked. - title: - type: string - description: The title of the tracking setting. - description: - type: string - description: A description about the event that is being tracked. - enabled: - type: boolean - description: Indicates if this tracking setting is currently enabled. + type: array + items: + $ref: '#/definitions/advanced_stats_country' examples: application/json: - result: - - name: open - title: Open Tracking - description: lorem ipsum... . - enabled: true - security: - - Authorization: [] - /tracking_settings/google_analytics: + - date: '2015-10-11' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-12' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-13' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-14' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-15' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-16' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-17' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-18' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-19' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-20' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-21' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 1 + unique_clicks: 0 + unique_opens: 1 + - date: '2015-10-22' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-23' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-24' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-25' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-26' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-27' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-28' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-29' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-30' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-31' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-01' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-02' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-03' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-04' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-05' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-06' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-07' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-08' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-09' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-10' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + /mail_settings/footer: parameters: [] get: - summary: Retrieve Google Analytics Settings + summary: Retrieve footer mail settings description: |- - **This endpoint allows you to retrieve your current setting for Google Analytics.** - - For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - - We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + **This endpoint allows you to retrieve your current Footer mail settings.** - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: GET_tracking_settings-google_analytics - consumes: - - application/json + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-footer + consumes: [] produces: - application/json parameters: [] @@ -12577,30 +12788,23 @@ paths: '200': description: '' schema: - $ref: '#/definitions/google_analytics_settings' + $ref: '#/definitions/mail_settings_footer' examples: application/json: enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' + html_content: Example HTML content + plain_content: Example plain content security: - Authorization: [] patch: - summary: Update Google Analytics Settings + summary: Update footer mail settings description: |- - **This endpoint allows you to update your current setting for Google Analytics.** - - For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - - We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + **This endpoint allows you to update your current Footer mail settings.** - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: PATCH_tracking_settings-google_analytics + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-footer consumes: - application/json produces: @@ -12609,201 +12813,116 @@ paths: - name: body in: body schema: - $ref: '#/definitions/google_analytics_settings' + $ref: '#/definitions/mail_settings_footer' example: enabled: true - utm_source: sendgrid.com - utm_medium: email - utm_term: '' - utm_content: '' - utm_campaign: website + html_content: ... + plain_content: ... responses: '200': description: '' schema: - $ref: '#/definitions/google_analytics_settings' + $ref: '#/definitions/mail_settings_footer' examples: application/json: enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' + html_content: Example HTML content + plain_content: Example plain content security: - Authorization: [] - /mail_settings: + /mail_settings/forward_bounce: parameters: [] get: - summary: Retrieve all mail settings + summary: Retrieve forward bounce mail settings description: |- - **This endpoint allows you to retrieve a list of all mail settings.** + **This endpoint allows you to retrieve your current bounce forwarding mail settings.** + + Activating this setting allows you to specify an email address to which bounce reports are forwarded. Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings - consumes: - - application/json + operationId: GET_mail_settings-forward_bounce + consumes: [] produces: - application/json - parameters: - - name: limit - in: query - description: The number of settings to return. - type: integer - - name: offset - in: query - description: Where in the list of results to begin displaying settings. - type: integer + parameters: [] responses: '200': description: '' schema: - type: object - properties: - result: - type: array - description: The list of all mail settings. - items: - type: object - properties: - title: - type: string - description: The title of the mail setting. - enabled: - type: boolean - description: Indicates if this mail setting is currently enabled. - name: - type: string - description: The name of the mail setting. - description: - type: string - description: A description of the mail setting. - required: - - title - - enabled - - name - - description - required: - - result + $ref: '#/definitions/mail_settings_forward_bounce' examples: application/json: - result: - - title: Address Whitelist - enabled: false - name: address_whitelist - description: Address / domains that should never have email suppressed. - - title: BCC - enabled: false - name: bcc - description: Automatically BCC an address for every e-mail sent. - - title: Bounce Purge - enabled: false - name: bounce_purge - description: Allows you to automatically purge bounce records from SendGrid after a specified number of days. - - title: Event Notification - enabled: true - name: event_notify - description: 'Controls notifications for events, such as bounces, clicks, and opens.' - - title: Footer - enabled: false - name: footer - description: Allows you to add a custom footer to outgoing email. - - title: Forward Bounce - enabled: true - name: forward_bounce - description: Allows you to forward bounces to a specific email address. - - title: Forward Spam - enabled: false - name: forward_spam - description: Allows for a copy of spam reports to be forwarded to an email address. - - title: Legacy Email Template - enabled: true - name: template - description: Allows you to customize your outgoing HTML emails. - - title: Plain Content - enabled: false - name: plain_content - description: Convert your plain text emails to HTML. - - title: Spam Checker - enabled: true - name: spam_check - description: Check outbound messages for spam content. + enabled: false + email: null security: - Authorization: [] - '/ips/pools/{pool_name}': - parameters: - - name: pool_name - in: path - description: The name of the IP pool that you want to retrieve the IP addresses from. - required: true - type: string - get: - summary: Retrieve all IPs in a specified pool. + patch: + summary: Update forward bounce mail settings description: |- - **This endpoint allows you to list all of the IP addresses that are in a specific IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + **This endpoint allows you to update your current bounce forwarding mail settings.** - IP pools can only be used with whitelabeled IP addresses. + Activating this setting allows you to specify an email address to which bounce reports are forwarded. - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: GET_ips-pools-pool_name + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-forward_bounce consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_forward_bounce' + example: + enabled: true + email: example@example.com responses: '200': description: '' schema: - type: object - properties: - pool_name: - type: string - description: The name of the IP pool. - maxLength: 64 - ips: - type: array - description: The list of IP addresses that belong to this IP pool. - items: - type: string - required: - - pool_name - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - field: - type: string - description: The name of the error. - message: - type: string - description: A message explaining why the IP addresses could not be listed. + $ref: '#/definitions/mail_settings_forward_bounce' + examples: + application/json: + email: '' + enabled: true + security: + - Authorization: [] + /mail_settings/forward_spam: + parameters: [] + get: + summary: Retrieve forward spam mail settings + description: |- + **This endpoint allows you to retrieve your current Forward Spam mail settings.** + + Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-forward_spam + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/mail_settings_forward_spam' examples: application/json: - errors: - - field: error - message: Unable to locate specified IPs Pool + email: '' + enabled: true security: - Authorization: [] - delete: - summary: Delete an IP pool. + patch: + summary: Update forward spam mail settings description: |- - **This endpoint allows you to delete an IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + **This endpoint allows you to update your current Forward Spam mail settings.** - IP pools can only be used with whitelabeled IP addresses. + Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: DELETE_ips-pools-pool_name + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-forward_spam consumes: - application/json produces: @@ -12812,36 +12931,59 @@ paths: - name: body in: body schema: - type: 'null' + $ref: '#/definitions/mail_settings_forward_spam' + example: + email: '' + enabled: false responses: - '204': + '200': description: '' schema: - type: object - '404': + $ref: '#/definitions/mail_settings_forward_spam' + examples: + application/json: + email: '' + enabled: false + security: + - Authorization: [] + /mail_settings/plain_content: + parameters: [] + get: + summary: Retrieve plain content mail settings + description: |- + **This endpoint allows you to retrieve your current Plain Content mail settings.** + + The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-plain_content + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': description: '' schema: type: object properties: - error: - type: string - description: An error explaining why the pool could not be deleted. + enabled: + type: boolean + description: Indicates if the Plain Content mail setting is enabled. examples: application/json: - error: Unable to locate specified IPs Pool + enabled: false security: - Authorization: [] - put: - summary: Update an IP pool’s name. + patch: + summary: Update plain content mail settings description: |- - **This endpoint allows you to update the name of an IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + **This endpoint allows you to update your current Plain Content mail settings.** - IP pools can only be used with whitelabeled IP addresses. + The plain content setting will automatically convert any plain text emails that you send to HTML before sending. - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: PUT_ips-pools-pool_name + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-plain_content consumes: - application/json produces: @@ -12852,207 +12994,401 @@ paths: schema: type: object properties: - name: - type: string - description: The new name for your IP pool. - maxLength: 64 + enabled: + type: boolean + description: The new setting you would like to use for your Plain Content mail setting. example: - name: new_pool_name + enabled: false responses: '200': - description: '' - schema: - $ref: '#/definitions/ip_pool' - examples: - application/json: - name: new_pool_name - '404': description: '' schema: type: object properties: - errors: - type: array - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the name of your IP pool could not be updated. + enabled: + type: boolean + description: Indicates if your Plain Content mail setting is enabled. examples: application/json: - errors: - - field: null - message: ip pool not found + enabled: false security: - Authorization: [] - /ips: - parameters: [] + '/subusers/{subuser_name}/stats/monthly': + parameters: + - name: subuser_name + in: path + required: true + type: string get: - tags: - - IP Addresses - summary: Retrieve all IP addresses + summary: Retrieve the monthly email statistics for a single subuser description: |- - **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** + **This endpoint allows you to retrive the monthly email statistics for a specific subuser.** - Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - operationId: GET_ips - consumes: - - application/json + 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`. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: GET_subusers-subuser_name-stats-monthly + consumes: [] produces: - application/json parameters: - - name: ip + - name: date in: query - description: The IP address to get + description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD + required: true type: string - - name: exclude_whitelabels + - name: sort_by_metric in: query - description: Should we exclude whitelabels? - type: boolean - - name: subuser + 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 + type: string + default: delivered + - name: sort_by_direction in: query - description: The subuser you are requesting for. + description: The direction you want to sort. + required: false type: string + default: desc + enum: + - desc + - asc - name: limit in: query - description: The number of IPs you want returned at the same time. + description: Optional field to limit the number of results returned. + required: false type: integer - default: 10 + default: 5 - name: offset in: query - description: The offset for the number of IPs that you are requesting. + description: Optional beginning point in the list to retrieve from. + required: false type: integer default: 0 responses: '200': description: '' schema: - type: array - items: - type: object - properties: - ip: - type: string - description: An IP address. - subusers: - type: array - description: The subusers that are able to send email from this IP. - items: - type: string - rdns: - type: string - description: The reverse DNS record for this IP address. - pools: - type: array - description: The IP pools that this IP has been added to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: - - number - - 'null' - description: The date that the IP address was entered into warmup. - whitelabeled: - type: boolean - description: Indicates if this IP address has been whitelabeled. - required: - - ip - - subusers - - pools - - warmup - - start_date - - whitelabeled + $ref: '#/definitions/subuser_stats' + examples: + application/json: + 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 + security: + - Authorization: [] + /subusers/stats: + parameters: [] + get: + tags: + - Stats - Subuser Stats + summary: Retrieve email statistics for your subusers. + 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. + + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: GET_subusers-stats + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + description: Limits the number of results returned per page. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results from. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - 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 + type: string + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string + responses: + '200': + description: '' + schema: + $ref: '#/definitions/stats' examples: application/json: - - ip: 127.0.0.1 - subusers: - - example_subuser1 - - example_subuser2 - rdns: o1.em.example.com - pools: [] - warmup: true - start_date: 1250337600 - whitelabeled: true - - ip: 127.0.0.1 - subusers: [] - pools: [] - warmup: false - start_date: null - whitelabeled: false + - 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 security: - Authorization: [] - '/ips/warmup/{ip_address}': - parameters: - - name: ip_address - in: path - description: The IP address that you want to remove from warmup mode. - required: true - type: string - delete: - summary: Remove an IP from warmup + /user/account: + parameters: [] + get: + tags: + - Users API + summary: Get a user's account information. description: |- - **This endpoint allows you to remove an IP address from warmup mode.** + **This endpoint allows you to retrieve your user account details.** - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + Your user's account information includes the user's account type and reputation. - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - operationId: DELETE_ips-warmup-ip_address - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The errors that were encountered. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the IP couldn't be removed from warmup. - examples: - application/json: - errors: - - field: null - message: resource not found - security: - - Authorization: [] - get: - summary: Retrieve warmup status for a specific IP address - description: |- - **This endpoint allows you to retrieve the warmup status for a specific IP address.** + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. + For more information about your user profile: - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - operationId: GET_ips-warmup-ip_address - consumes: - - application/json + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: GET_user-account + consumes: [] produces: - application/json parameters: [] @@ -13060,332 +13396,118 @@ paths: '200': description: '' schema: - $ref: '#/definitions/ip_warmup_response' - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The errors that were encountered. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the warmup status could not be retrieved. - examples: - application/json: - errors: - - field: null - message: resource not found - security: - - Authorization: [] - /suppression/unsubscribes: - parameters: [] - get: - tags: - - Suppression Management - Global Suppressions - summary: Retrieve all global suppressions - description: |- - **This endpoint allows you to retrieve a list of all email address that are globally suppressed.** - - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: GET_suppression-unsubscribes - consumes: - - application/json - produces: - - application/json - parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive). - type: integer - - name: limit - in: query - description: The number of results to display on each page. - type: integer - - name: offset - in: query - description: The point in the list of results to begin displaying global suppressions. - type: integer - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the recipient was added to the global suppression list. - email: - type: string - description: The email address of the recipient who is globally suppressed. - required: - - created - - email - examples: - application/json: - - created: 1443651141 - email: user1@example.com - - created: 1443651154 - email: user2@example.com - security: - - Authorization: [] - /asm/suppressions/global: - parameters: [] - post: - tags: - - Suppression Management - Global Suppressions - summary: Add recipient addresses to the global suppression group. - description: |- - **This endpoint allows you to add one or more email addresses to the global suppressions group.** - - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: POST_asm-suppressions-global - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - recipient_emails: - type: array - description: 'The email address, or addresses, that you want to add to the global suppressions group.' - items: - type: string - example: - recipient_emails: - - test1@example.com - - test2@example.com - responses: - '201': - description: '' - schema: - type: object - properties: - recipient_emails: - type: array - description: The email addresses that are globally suppressed - items: - type: string - required: - - recipient_emails - examples: - application/json: - recipient_emails: - - test1@example.com - - test2@example.com - security: - - Authorization: [] - /suppression/blocks: - parameters: [] - delete: - tags: - - Blocks API - summary: Delete blocks - description: |- - **This endpoint allows you to delete all email addresses on your blocks list.** - - There are two options for deleting blocked emails: - - 1. You can delete all blocked emails by setting `delete_all` to true in the request body. - 2. You can delete some blocked emails by specifying the email addresses in an array in the request body. - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: DELETE_suppression-blocks - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: + title: GET User Account response type: object properties: - delete_all: - type: boolean - description: Indicates if you want to delete all blocked email addresses. - emails: - type: array - description: The specific blocked email addresses that you want to delete. - items: - type: string - example: - delete_all: false - emails: - - example1@example.com - - example2@example.com - responses: - '204': - description: '' - schema: - type: object - properties: {} + type: + type: string + description: The type of account for this user. + enum: + - free + - paid + reputation: + type: number + description: The sender reputation for this user. + required: + - type + - reputation + examples: + application/json: + reputation: 100 + type: paid security: - Authorization: [] + /user/email: + parameters: [] get: tags: - - Blocks API - summary: Retrieve all blocks + - Users API + summary: Retrieve your account email address description: |- - **This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** + **This endpoint allows you to retrieve the email address currently on file for your account.** - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: GET_suppression-blocks - consumes: - - application/json + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: GET_user-email + consumes: [] produces: - application/json - parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a blocked email was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a blocked email was created (inclusive). - type: integer - - name: limit - in: query - description: Limit the number of results to be displayed per page. - type: integer - - name: offset - in: query - description: The point in the list to begin displaying results. - type: integer + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the blocks list. - email: - type: string - description: The email address that was added to the block list. - reason: - type: string - description: An explanation for the reason of the block. - status: - type: string - description: The status of the block. - required: - - created - - email - - reason - - status + type: object + properties: + email: + type: string + description: The email address currently on file for your account. + required: + - email examples: application/json: - - created: 1443651154 - email: user1@example.com - reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' - status: 4.0.0 + email: test@example.com security: - Authorization: [] - /suppression/invalid_emails: - parameters: [] - get: - summary: Retrieve all invalid emails + put: + tags: + - Users API + summary: Update your account email address description: |- - **This endpoint allows you to retrieve a list of all invalid email addresses.** + **This endpoint allows you to update the email address currently on file for your account.** - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + For more information about your user profile: - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: GET_suppression-invalid_emails + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: PUT_user-email consumes: - application/json produces: - application/json parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when an invalid email was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when an invalid email was created (inclusive). - type: integer - - name: limit - in: query - description: Limit the number of results to be displayed per page. - type: integer - - name: offset - in: query - description: Paging offset. The point in the list to begin displaying results. - type: integer + - name: body + in: body + schema: + type: object + properties: + email: + type: string + description: The new email address that you would like to use for your account. + example: + email: example@example.com responses: '200': description: '' schema: - type: array - description: The list of invalid email addresses. - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the invalid emails list. - email: - type: string - description: The email address that was marked as invalid. - reason: - type: string - description: The reason that the email address was marked as invalid. - required: - - created - - email - - reason - examples: - application/json: - - created: 1449953655 - email: user1@example.com - reason: Mail domain mentioned in email address is unknown - - created: 1449939373 - email: user1@example.com - reason: Mail domain mentioned in email address is unknown + type: object + properties: + email: + type: string + description: The current email address on file for your account. + required: + - email security: - Authorization: [] - delete: - summary: Delete invalid emails + /user/password: + parameters: [] + put: + tags: + - Users API + summary: Update your password description: |- - **This endpoint allows you to remove email addresses from your invalid email address list.** - - There are two options for deleting invalid email addresses: - - 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. - 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. + **This endpoint allows you to update your password.** - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + For more information about your user profile: - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: DELETE_suppression-invalid_emails + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: PUT_user-password consumes: - application/json produces: [] @@ -13395,104 +13517,120 @@ paths: schema: type: object properties: - delete_all: - type: boolean - description: Indicates if you want to remove all email address from the invalid emails list. - emails: - type: array - description: The list of specific email addresses that you want to remove. - items: - type: string + new_password: + type: string + description: The new password you would like to use for your account. + old_password: + type: string + description: The old password for your account. + required: + - new_password + - old_password example: - delete_all: false - emails: - - example1@example.com - - example2@example.com + new_password: new_password + old_password: old_password responses: - '204': + '200': description: '' - schema: - type: object - properties: {} security: - Authorization: [] - /suppression/spam_reports: + /user/username: parameters: [] get: - summary: Retrieve all spam reports + tags: + - Users API + summary: Retrieve your username + description: |- + **This endpoint allows you to retrieve your current account username.** + + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: GET_user-username + consumes: [] + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + username: + type: string + description: Your account username. + user_id: + type: integer + description: The user ID for your account. + required: + - username + - user_id + examples: + application/json: + username: test_username + user_id: 1 + security: + - Authorization: [] + put: + tags: + - Users API + summary: Update your username description: |- - **This endpoint allows you to retrieve all spam reports.** + **This endpoint allows you to update the username for your account.** - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: GET_suppression-spam_reports + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: PUT_user-username consumes: - application/json produces: - application/json parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a spam report was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a spam report was created (inclusive). - type: integer - - name: limit - in: query - description: Limit the number of results to be displayed per page. - type: integer - - name: offset - in: query - description: Paging offset. The point in the list to begin displaying results. - type: integer + - name: body + in: body + schema: + type: object + properties: + username: + type: string + description: The new username you would like to use for your account. + example: + username: test_username responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the spam report was made. - email: - type: string - description: The email address of the recipient who marked your message as spam. - ip: - type: string - description: The IP address that the message was sent on. - required: - - created - - email - - ip + type: object + properties: + username: + type: string + description: The current username on file for your account. + required: + - username examples: application/json: - - created: 1443651141 - email: user1@example.com - ip: 10.63.202.100 - - created: 1443651154 - email: user2@example.com - ip: 10.63.202.100 + username: test_username security: - Authorization: [] - delete: - summary: Delete spam reports + /user/webhooks/event/test: + parameters: [] + post: + tags: + - Webhooks + summary: 'Test Event Notification Settings ' description: |- - **This endpoint allows you to delete your spam reports.** - - There are two options for deleting spam reports: - - 1) You can delete all spam reports by setting "delete_all" to true in the request body. - 2) You can delete some spam reports by specifying the email addresses in an array in the request body. + **This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: DELETE_suppression-spam_reports + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + operationId: POST_user-webhooks-event-test consumes: - application/json produces: [] @@ -13502,177 +13640,124 @@ paths: schema: type: object properties: - delete_all: - type: boolean - description: Indicates if you want to delete all email addresses on the spam report list. - emails: - type: array - description: A list of specific email addresses that you want to remove from the spam report list. - items: - type: string + url: + type: string + description: The URL where you would like the test notification to be sent. example: - delete_all: false - emails: - - example1@example.com - - example2@example.com + url: url responses: '204': description: '' - schema: - type: object - properties: {} security: - Authorization: [] - '/asm/suppressions/{email}': + '/whitelabel/domains/{domain_id}/subuser': parameters: - - name: email + - name: domain_id in: path - description: The email address that you want to search suppression groups for. required: true type: string - get: - tags: - - Suppression Management - Suppressions - summary: Retrieve all suppression groups for an email address + post: + summary: Associate a domain whitelabel with a given user. description: |- - **This endpoint will return a list of all suppression groups, indicating if the given email address is suppressed for each group.** + **This endpoint allows you to associate a specific domain whitelabel with a subuser.** - Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses. - operationId: GET_asm-suppressions-email + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | domain_id | integer | ID of the domain whitelabel to associate with the subuser. | + operationId: POST_whitelabel-domains-domain_id-subuser consumes: - application/json produces: - application/json - parameters: [] - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: type: object properties: - suppressions: - type: array - description: The array of suppression groups. - items: - type: object - properties: - description: - type: string - description: The description of the suppression group. - id: - type: integer - description: The id of the suppression group. - is_default: - type: boolean - description: Indicates if the suppression group is set as the default. - name: - type: string - description: The name of the suppression group. - suppressed: - type: boolean - description: Indicates if the given email address is suppressed for this group. - required: - - description - - id - - is_default - - name - - suppressed + username: + type: string + description: Username to associate with the domain whitelabel. required: - - suppressions - examples: - application/json: - suppressions: - - description: Optional description. - id: 1 - is_default: true - name: Weekly News - suppressed: true - - description: Some daily news. - id: 2 - is_default: true - name: Daily News - suppressed: true - - description: An old group. - id: 2 - is_default: false - name: Old News - suppressed: false - security: - - Authorization: [] - /asm/suppressions: - parameters: [] - get: - tags: - - Suppression Management - Suppressions - summary: Retrieve all suppressions - description: |- - **This endpoint allows you to retrieve a list of all suppressions.** - - Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses. - operationId: GET_asm-suppressions - consumes: - - application/json - produces: - - application/json - parameters: [] + - username + example: + username: jane@example.com responses: - '200': + '201': description: '' schema: - type: array - items: - type: object - properties: - email: - type: string - description: The email address that was suppressed. - group_id: - type: integer - description: The id of the suppression group that this email address belongs to. - group_name: - type: string - description: The name of the suppression group that this email address belongs to. - created_at: - type: integer - description: A UNIX timestamp indicating when the suppression was created. - required: - - email - - group_id - - group_name - - created_at + $ref: '#/definitions/whitelabel:domain_spf' examples: application/json: - - email: test1@example.com - group_id: 1 - group_name: Weekly News - created_at: 1410986704 - - email: test1@example.com - group_id: 2 - group_name: Daily News - created_at: 1411493671 - - email: test2@example.com - group_id: 2 - group_name: Daily News - created_at: 1411493671 + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - /user/email: - parameters: [] - get: + '/whitelabel/domains/{id}/ips/{ip}': + parameters: + - name: id + in: path + required: true + type: string + - name: ip + in: path + required: true + type: string + delete: tags: - - Users API - summary: Retrieve your account email address + - Whitelabel - Domains + summary: Remove an IP from a domain whitelabel. description: |- - **This endpoint allows you to retrieve the email address currently on file for your account.** + **This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - For more information about your user profile: + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: GET_user-email - consumes: - - application/json + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain whitelabel to delete the IP from. | + | ip | string | IP to remove from the domain whitelabel. | + operationId: DELETE_whitelabel-domains-id-ips-ip + consumes: [] produces: - application/json parameters: [] @@ -13680,31 +13765,65 @@ paths: '200': description: '' schema: - type: object - properties: - email: - type: string - description: The email address currently on file for your account. - required: - - email + $ref: '#/definitions/whitelabel:domain_spf' examples: application/json: - email: test@example.com + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - put: + '/whitelabel/domains/{id}/ips': + parameters: + - name: id + in: path + required: true + type: string + post: tags: - - Users API - summary: Update your account email address + - Whitelabel - Domains + summary: Add an IP to a domain whitelabel. description: |- - **This endpoint allows you to update the email address currently on file for your account.** + **This endpoint allows you to add an IP address to a domain whitelabel.** - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - For more information about your user profile: + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: PUT_user-email + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain to which you are adding an IP | + operationId: POST_whitelabel-domains-id-ips consumes: - application/json produces: @@ -13715,569 +13834,549 @@ paths: schema: type: object properties: - email: + ip: type: string - description: The new email address that you would like to use for your account. + description: IP to associate with the domain. Used for manually specifying IPs for custom SPF. + required: + - ip example: - email: example@example.com + ip: 192.168.0.1 responses: '200': description: '' schema: - type: object - properties: - email: - type: string - description: The current email address on file for your account. - required: - - email + $ref: '#/definitions/whitelabel:domain_spf' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - /user/username: + /whitelabel/domains/default: parameters: [] get: tags: - - Users API - summary: Retrieve your username + - Whitelabel - Domains + summary: Get the default domain whitelabel. description: |- - **This endpoint allows you to retrieve your current account username.** + **This endpoint allows you to retrieve the default whitelabel for a domain.** - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - For more information about your user profile: + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: GET_user-username - consumes: - - application/json + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | domain | string |The domain to find a default domain whitelabel for. | + operationId: GET_whitelabel-domains-default + consumes: [] produces: - application/json parameters: [] responses: '200': description: '' + schema: + $ref: '#/definitions/whitelabel:domain_spf' + security: + - Authorization: [] + '/whitelabel/links/{link_id}/subuser': + parameters: + - name: link_id + in: path + description: The id of the link whitelabel you want to associate. + required: true + type: integer + post: + summary: Associate a Link Whitelabel + description: |- + **This endpoint allows you to associate a link whitelabel with a subuser account.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: POST_whitelabel-links-link_id-subuser + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: type: object properties: username: type: string - description: Your account username. - user_id: - type: integer - description: The user ID for your account. - required: - - username - - user_id + description: The username of the subuser account that you want to associate the link whitelabel with. + example: + username: jane@example.com + responses: + '200': + description: '' + schema: + $ref: '#/definitions/link_whitelabel' examples: application/json: - username: test_username - user_id: 1 + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - put: + /whitelabel/links/default: + parameters: [] + get: tags: - - Users API - summary: Update your username + - Whitelabel - Links + summary: Retrieve a Default Link Whitelabel description: |- - **This endpoint allows you to update the username for your account.** + **This endpoint allows you to retrieve the default link whitelabel.** - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: + - For more information about your user profile: + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: PUT_user-username - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: GET_whitelabel-links-default + consumes: [] produces: - application/json parameters: - - name: body - in: body - schema: - type: object - properties: - username: - type: string - description: The new username you would like to use for your account. - example: - username: test_username + - name: domain + in: query + description: The domain to match against when finding a corresponding link whitelabel. + type: string responses: '200': description: '' schema: - type: object - properties: - username: - type: string - description: The current username on file for your account. - required: - - username + $ref: '#/definitions/link_whitelabel' examples: application/json: - username: test_username + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - /mail/send/beta: + /whitelabel/links: parameters: [] - post: + get: tags: - - Mail Send - summary: v3 Mail Send Beta + - Whitelabel - Links + summary: Retrieve all link whitelabels description: |- - This endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - * Top level parameters are referred to as "global". - * Individual fields within the personalizations array will override any other global, or “message level”, parameters that are defined outside of personalizations. + **This endpoint allows you to retrieve all link whitelabels.** - For an overview of the v3 Mail Send endpoint, please visit our [v3 API Reference](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html) + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - For more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html). - operationId: POST_mail-send-beta - consumes: - - application/json + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: GET_whitelabel-links + consumes: [] produces: - application/json parameters: - - name: body - in: body + - name: limit + in: query + description: Limits the number of results returned per page. + type: integer + responses: + '200': + description: '' schema: - type: object - properties: - personalizations: - type: array - description: An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. - uniqueItems: false - maxItems: 100 - items: - type: object - properties: - to: - type: array - description: 'An array of recipients. Each object within this array may contain the name, but must always contain the email, of a recipient.' - minItems: 1 - maxItems: 100 - items: - type: object - properties: - '': - $ref: '#/definitions/email_object' - cc: - type: array - description: 'An array of recipients who will receive a copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.' - maxItems: 100 - items: - type: object - properties: - '': - $ref: '#/definitions/email_object' - bcc: - type: array - description: 'An array of recipients who will receive a blind carbon copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.' - maxItems: 100 - items: - type: object - properties: - '': - $ref: '#/definitions/email_object' - subject: - type: string - description: 'The subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310' - minLength: 1 - headers: - type: object - description: 'A collection of JSON key/value pairs allowing you to specify specific handling instructions for your email. You may not overwrite the following headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC' - substitutions: - type: object - description: 'A collection of key/value pairs following the pattern "substitution_tag":"value to substitute". All are assumed to be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters.' - maxProperties: 10000 - custom_args: - type: object - description: 'Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. May not exceed 10,000 bytes.' - send_at: - type: integer - description: A unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden. - required: - - to - from: - type: object - description: An email object containing the email address and name of the sender. - properties: - '': - $ref: '#/definitions/email_object' - reply_to: - type: object - description: An email object containing the email address and name of the individual who should receive responses to your email. - properties: - '': - $ref: '#/definitions/email_object' - subject: - type: string - description: 'The global, or “message level”, subject of your email. This may be overridden by personalizations[x].subject.' - minLength: 1 - content: - type: array - description: 'An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one mime type. To include more than one mime type, simply add another object to the array containing the `type` and `value` parameters.' - items: - type: object - properties: - type: - type: string - description: 'The mime type of the content you are including in your email. For example, “text/plain” or “text/html”.' - minLength: 1 - value: - type: string - description: The actual content of the specified mime type that you are including in your email. - minLength: 1 - required: - - type - - value - attachments: - type: array - description: An array of objects in which you can specify any attachments you want to include. - items: - type: object - properties: - content: - type: string - description: The Base64 encoded content of the attachment. - minLength: 1 - type: - type: string - description: 'The mime type of the content you are attaching. For example, “text/plain” or “text/html”.' - minLength: 1 - filename: - type: string - description: The filename of the attachment. - disposition: - type: string - default: attachment - description: 'The content-disposition of the attachment specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file being displayed automatically within the message while “attachment” results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file).' - enum: - - inline - - attachment - content_id: - type: string - description: 'The content id for the attachment. This is used when the disposition is set to “inline” and the attachment is an image, allowing the file to be displayed within the body of your email.' - required: - - content - - filename - template_id: - type: string - description: 'The id of a template that you would like to use. If you use a template that contains a subject and content (either text or html), you do not need to specify those at the personalizations nor message level. ' - sections: - type: object - description: An object of key/value pairs that define block sections of code to be used as substitutions. - headers: - type: object - description: An object containing key/value pairs of header names and the value to substitute for them. You must ensure these are properly encoded if they contain unicode characters. Must not be one of the reserved headers. - categories: - type: array - description: 'An array of category names for this message. Each category name may not exceed 255 characters. ' - uniqueItems: true - maxItems: 10 - items: - type: string - maxLength: 255 - custom_args: - type: object - description: 'Values that are specific to the entire send that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by personalizations[x].custom_args if that parameter has been defined. Total custom args size may not exceed 10,000 bytes.' - send_at: - type: integer - description: 'A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the personalizations[x].send_at parameter. Scheduling more ta 72 hours in advance is forbidden.' - batch_id: + type: array + items: + $ref: '#/definitions/link_whitelabel' + examples: + application/json: + - id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: true + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + - id: 2 + domain: example2.com + subdomain: news + username: john@example.com + user_id: 8 + default: false + valid: false + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: news.example2.com + data: sendgrid.net + owner_cname: + valid: false + type: cname + host: 8.example2.com + data: sendgrid.net + security: + - Authorization: [] + post: + tags: + - Whitelabel - Links + summary: Create a Link Whitelabel + description: |- + **This endpoint allows you to create a new link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: POST_whitelabel-links + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: Number of domains to return. + type: integer + default: 50 + - name: offset + in: query + description: Paging offset. + type: integer + default: 0 + - name: body + in: body + schema: + type: object + properties: + domain: type: string - description: 'This ID represents a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch, and also enables you to cancel or pause the delivery of that batch. For more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send.html ' - asm: - type: object - description: An object allowing you to specify how to handle unsubscribes. - properties: - group_id: - type: integer - description: The unsubscribe group to associate with this email. - groups_to_display: - type: array - description: An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page. - maxItems: 25 - items: - type: integer - required: - - group_id - ip_pool_name: + description: The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address. + subdomain: + type: string + description: The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel. + default: + type: boolean + description: 'Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.' + enum: + - true + - false + required: + - domain + - subdomain + example: + domain: example.com + subdomain: mail + default: true + responses: + '201': + description: '' + schema: + $ref: '#/definitions/link_whitelabel' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + security: + - Authorization: [] + /api_keys: + parameters: [] + post: + summary: Create API keys + description: |- + **This enpoint allows you to create a new random API Key for the user.** + + A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. + + There is a limit of 100 API Keys on your account. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. + operationId: create-api-keys + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name you will use to describe this API Key. + scopes: + type: array + description: The individual permissions that you are giving to this API Key. + items: + type: string + sample: type: string - description: The IP Pool that you would like to send this email from. - minLength: 2 - maxLength: 64 - mail_settings: - type: object - description: A collection of different mail settings that you can use to specify how you would like this email to be handled. - properties: - bcc: - type: object - description: This allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - email: - type: string - description: The email address that you would like to receive the BCC. - format: email - bypass_list_management: - type: object - description: Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - footer: - type: object - description: The default footer that you would like included on every email. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - text: - type: string - description: The plain text content of your footer. - html: - type: string - description: The HTML content of your footer. - sandbox_mode: - type: object - description: This allows you to send a test email to ensure that your request body is valid and formatted correctly. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - spam_check: - type: object - description: This allows you to test the content of your email for spam. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - threshold: - type: integer - description: 'The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam.' - minimum: 1 - maximum: 10 - post_to_url: - type: string - description: An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to. - tracking_settings: - type: object - description: Settings to determine how you would like to track the metrics of how your recipients interact with your email. - properties: - click_tracking: - type: object - description: Allows you to track whether a recipient clicked a link in your email. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - enable_text: - type: boolean - description: Indicates if this setting should be included in the text/plain portion of your email. - open_tracking: - type: object - description: 'Allows you to track whether the email was opened or not, but including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.' - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - substitution_tag: - type: string - description: Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel. - subscription_tracking: - type: object - description: 'Allows you to insert a subscription management link at the bottom of the text and html bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag.' - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - text: - type: string - description: 'Text to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>' - html: - type: string - description: 'HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>' - substitution_tag: - type: string - description: 'A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting.' - ganalytics: - type: object - description: Allows you to enable tracking provided by Google Analytics. - properties: - enable: - type: boolean - description: Indicates if this setting is enabled. - utm_source: - type: string - description: 'Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)' - utm_medium: - type: string - description: Name of the marketing medium. (e.g. Email) - utm_term: - type: string - description: "Used to identify any paid keywords.\t" - utm_content: - type: string - description: "Used to differentiate your campaign from advertisements.\t" - utm_campaign: - type: string - description: "The name of the campaign.\t" required: - - personalizations - - from - - reply_to - - subject - - content + - name example: - personalizations: - - to: - - email: john.doe@example.com - name: John Doe - cc: - - email: jane.doe@example.com - name: Jane Doe - bcc: - - email: sam.doe@example.com - name: Sam Doe - subject: 'Hello, World!' - headers: - X-Accept-Language: en - X-Mailer: MyApp - substitutions: - sub: - '%name%': - - John - - Jane - - Sam - custom_args: - customerAccountNumber: '[CUSTOMER ACCOUNT NUMBER GOES HERE]' - activationAttempt: '1' - New Argument 1: New Value 1 - send_at: 1409348513 - from: - email: sam.smith@example.com - name: Sam Smith - reply_to: - email: sam.smith@example.com - name: Sam Smith - subject: 'Hello, World!' - content: - - type: text/html - value: '

Hello, world!

' - attachments: - - content: '[BASE64 encoded content block here]' - type: jpg - name: file1 - filename: file1.jpg - disposition: inline - content_id: ii_139db99fdb5c3704 - template_id: '[YOUR TEMPLATE ID GOES HERE]' - sections: - section: - ':sectionName1': section 1 text - ':sectionName2': section 2 text - headers: {} - categories: - - category1 - - category2 - custom_args: - customerAccountNumber: '[CUSTOMER ACCOUNT NUMBER GOES HERE]' - activationAttempt: '1' - New Argument 1: New Value 1 - send_at: 1409348513 - batch_id: '[YOUR BATCH ID GOES HERE]' - asm: - group_id: 1 - groups_to_display: - - 1 - - 2 - - 3 - ip_pool_name: '[YOUR POOL NAME GOES HERE]' - mail_settings: - bcc: - enable: true - email: ben.doe@example.com - bypass_list_management: - enable: true - footer: - enable: true - text: 'Thanks,/n The SendGrid Team' - html:

Thanks
The SendGrid Team

- sandbox_mode: - enable: false - spam_check: - enable: true - threshold: 3 - post_to_url: 'http://example.com/compliance' - tracking_settings: - click_tracking: - enable: true - enable_text: true - open_tracking: - enable: true - substitution_tag: '%opentrack' - subscription_tracking: - enable: true - text: If you would like to unsubscribe and stop receiveing these emails <% click here %>. - html: If you would like to unsubscribe and stop receiving these emails <% clickhere %>. - substitution_tag: <%click here%> - ganalytics: - enable: true - utm_campaign: '[NAME OF YOUR REFERRER SOURCE]' - utm_medium: '[NAME OF YOUR MARKETING MEDIUM e.g. email]' - utm_term: '[IDENTIFY PAID KEYWORDS HERE]' - utm_content: '[USE THIS SPACE TO DIFFERENTIATE YOUR EMAIL FROM ADS]' - utm_name: '[NAME OF YOUR CAMPAIGN]' + name: My API Key + scopes: + - mail.send + - alerts.create + - alerts.read + sample: data responses: - '202': + '201': description: '' schema: type: object - properties: {} + properties: + api_key: + type: string + api_key_id: + type: string + name: + type: string + scopes: + type: array + items: + type: string + examples: + application/json: + api_key: SG.xxxxxxxx.yyyyyyyy + api_key_id: xxxxxxxx + name: My API Key + scopes: + - mail.send + - alerts.create + - alerts.read '400': description: '' schema: - $ref: '#/definitions/errors' + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: name + message: missing required argument '401': description: '' schema: - $ref: '#/definitions/errors' - '413': + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '403': description: '' schema: - $ref: '#/definitions/errors' + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: Cannot create more than 100 API Keys security: - Authorization: [] -definitions: - suppression_group_unsubscribes: - allOf: - - $ref: '#/definitions/suppression_group' - - properties: - unsubscribes: - type: integer - description: The unsubscribes associated with this group. - required: - - unsubscribes - type: object - mail_settings_patch: - type: object - properties: - enabled: - type: boolean - description: Indicates if the mail setting is enabled. - email: + get: + summary: Retrieve all API Keys belonging to the authenticated user + description: |- + **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + operationId: GET_api_keys + consumes: [] + produces: + - application/json + parameters: + - name: limit + in: query + type: integer + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/api_key_name_id' + examples: + application/json: + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + '/asm/groups/{group_id}/suppressions/search': + parameters: + - name: group_id + in: path + description: The ID of the suppression group that you would like to search. + required: true type: string - description: The email address of the recipient. - example: - enabled: true - email: email@example.com - 'global:empty_request': - type: 'null' + post: + summary: Search for suppressions within a group + description: |- + **This endpoint allows you to search a suppression group for multiple suppressions.** + + When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group. + + Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). + operationId: POST_asm-groups-group_id-suppressions-search + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + recipient_emails: + type: array + description: The list of email address that you want to search the suppression group for. + items: + type: string + required: + - recipient_emails + example: + recipient_emails: + - exists1@example.com + - exists2@example.com + - doesnotexists@example.com + responses: + '200': + description: '' + schema: + type: object + properties: + recipient_emails: + type: array + description: The email address from your search that do exist in the suppression group. + items: + type: string + required: + - recipient_emails + examples: + application/json: + recipient_emails: + - exists1@example.com + - exists2@example.com + security: + - Authorization: [] +definitions: contactdb_recipient_count: type: object properties: @@ -14288,15 +14387,6 @@ definitions: - recipient_count example: recipient_count: 1234 - contactdb_custom_field_with_id: - allOf: - - $ref: '#/definitions/contactdb_custom_field' - - type: object - properties: - id: - type: number - description: The ID of the custom field. - title: ContactDB Custom field schema with ID. contactdb_custom_field: title: ContactDB Custom field schema. type: object @@ -14314,47 +14404,15 @@ definitions: example: name: first_name type: text - contactdb_segments_with_id: + contactdb_custom_field_with_id: allOf: + - $ref: '#/definitions/contactdb_custom_field' - type: object properties: id: type: number - description: The ID of the segment. - required: - - id - - $ref: '#/definitions/contactdb_segments' - transactional_template_version: - type: object - properties: - template_id: - type: string - description: The name of the original transactional template. - active: - type: integer - description: Set the new version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active. - enum: - - 0 - - 1 - name: - type: string - description: Name of the new transactional template version. - html_content: - type: string - description: The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. - plain_content: - type: string - description: Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. - subject: - type: string - description: Subject of the new transactional template version. Must include <%subject%> tag. - required: - - template_id - - active - - name - - html_content - - plain_content - - subject + description: The ID of the custom field. + title: ContactDB Custom field schema with ID. contactdb_segments: title: Create a Segment request type: object @@ -14393,16 +14451,47 @@ definitions: operator: eq and_or: or recipient_count: 1234 - mail_batch_id: + contactdb_segments_with_id: + allOf: + - type: object + properties: + id: + type: number + description: The ID of the segment. + required: + - id + - $ref: '#/definitions/contactdb_segments' + transactional_template_version: type: object properties: - batch_id: + template_id: type: string - pattern: '^[a-zA-Z0-9\-\_]' + description: The name of the original transactional template. + active: + type: integer + description: Set the new version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active. + enum: + - 0 + - 1 + name: + type: string + description: Name of the new transactional template version. + html_content: + type: string + description: The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. + plain_content: + type: string + description: Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. + subject: + type: string + description: Subject of the new transactional template version. Must include <%subject%> tag. required: - - batch_id - example: - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + - template_id + - active + - name + - html_content + - plain_content + - subject campaign_response: allOf: - $ref: '#/definitions/campaign_request' @@ -14415,6 +14504,20 @@ definitions: type: integer required: - status + 'global:id': + type: integer + mail_batch_id: + type: object + properties: + batch_id: + type: string + pattern: '^[a-zA-Z0-9\-\_]' + required: + - batch_id + example: + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + 'global:empty_request': + type: 'null' mail_settings_address_whitelabel: type: object properties: @@ -14431,20 +14534,42 @@ definitions: list: - email1@example.com - example.com - api_key_name_id: + mail_settings_bcc: type: object properties: - api_key_id: + email: type: string - description: 'The ID of your API Key. ' - name: + description: The email address that will be sent a blind carbon copy. + enabled: + type: boolean + description: Indicates if the BCC setting is enabled. + example: + email: example@example.com + enabled: false + mail_settings_patch: + type: object + properties: + enabled: + type: boolean + description: Indicates if the mail setting is enabled. + email: type: string - description: The name of your API Key. + description: The email address of the recipient. example: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - 'global:id': - type: integer + enabled: true + email: email@example.com + mail_settings_forward_spam: + type: object + properties: + email: + type: string + description: The email address where you would like the spam reports to be forwarded. + enabled: + type: boolean + description: Indicates if the Forward Spam setting is enabled. + example: + email: '' + enabled: true mail_settings_template: type: object properties: @@ -14458,6 +14583,18 @@ definitions: enabled: false html_content: |

<% body %>Example

+ api_key_name_id: + type: object + properties: + api_key_id: + type: string + description: 'The ID of your API Key. ' + name: + type: string + description: The name of your API Key. + example: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope mail_settings_forward_bounce: type: object properties: @@ -14472,30 +14609,16 @@ definitions: example: enabled: false email: null - mail_settings_forward_spam: - type: object - properties: - email: - type: string - description: The email address where you would like the spam reports to be forwarded. - enabled: - type: boolean - description: Indicates if the Forward Spam setting is enabled. - example: - email: '' - enabled: true - mail_settings_bcc: + suppression_group_unsubscribes: + allOf: + - $ref: '#/definitions/suppression_group' + - properties: + unsubscribes: + type: integer + description: The unsubscribes associated with this group. + required: + - unsubscribes type: object - properties: - email: - type: string - description: The email address that will be sent a blind carbon copy. - enabled: - type: boolean - description: Indicates if the BCC setting is enabled. - example: - email: example@example.com - enabled: false contactdb_list: title: ContactDB lists type: object @@ -14522,26 +14645,37 @@ definitions: properties: address: type: string + description: The street address for this user profile. address2: type: string + description: An optional second line for the street address of this user profile. city: type: string + description: The city for the user profile. company: type: string + description: That company that this user profile is associated with. country: type: string + description: Th country of this user profile. first_name: type: string + description: The first name of the user. last_name: type: string + description: The last name of the user. phone: type: string + description: The phone number for the user. state: type: string + description: The state for this user. website: type: string + description: The website associated with this user. zip: type: string + description: The zip code for this user. example: address: '1451 Larimer Street, 3rd floor' address2: '' @@ -14845,23 +14979,6 @@ definitions: - valid - legacy - dns - ip_warmup_response: - type: array - items: - type: object - properties: - ip: - type: string - description: The IP address. - start_date: - type: integer - description: A Unix timestamp indicating when the IP address was entered into warmup mode. - required: - - ip - - start_date - example: - - ip: 0.0.0.0 - start_date: 1409616000 ip_whitelabel: type: object properties: @@ -14949,6 +15066,23 @@ definitions: type: a host: o1.email.example.com data: 192.168.1.1 + ip_warmup_response: + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address. + start_date: + type: integer + description: A Unix timestamp indicating when the IP address was entered into warmup mode. + required: + - ip + - start_date + example: + - ip: 0.0.0.0 + start_date: 1409616000 ip_pool: type: object properties: @@ -16182,6 +16316,34 @@ definitions: message: type: string description: The message the API caller will receive. + parse-setting: + type: object + properties: + url: + type: string + description: The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL. + hostname: + type: string + description: 'A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, parse.yourdomain.com.' + spam_check: + type: boolean + description: Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain. + send_raw: + type: boolean + description: 'Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to "false", SendGrid will send a JSON payload of the content of your email. ' + example: + url: 'http://email.myhostname.com' + hostname: myhostname.com + spam_check: false + send_raw: true +parameters: + 'trait:authorizationHeader:Authorization': + name: Authorization + in: header + description: '' + required: true + type: string + default: Bearer <> securityDefinitions: Authorization: name: Authorization diff --git a/oai_stoplight.json b/oai_stoplight.json index f262797..99b0949 100644 --- a/oai_stoplight.json +++ b/oai_stoplight.json @@ -2065,6 +2065,40 @@ "summary": "" } }, + "parse-setting": { + "example": { + "hostname": "myhostname.com", + "send_raw": true, + "spam_check": false, + "url": "http://email.myhostname.com" + }, + "properties": { + "hostname": { + "description": "A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, parse.yourdomain.com.", + "type": "string" + }, + "send_raw": { + "description": "Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to \"false\", SendGrid will send a JSON payload of the content of your email. ", + "type": "boolean" + }, + "spam_check": { + "description": "Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain.", + "type": "boolean" + }, + "url": { + "description": "The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL.", + "type": "string" + } + }, + "type": "object", + "x-stoplight": { + "description": "", + "id": "parse-setting", + "name": "Parse Setting", + "public": true, + "summary": "" + } + }, "partner_settings_new_relic": { "properties": { "enable_subuser_statistics": { @@ -2635,36 +2669,47 @@ }, "properties": { "address": { + "description": "The street address for this user profile.", "type": "string" }, "address2": { + "description": "An optional second line for the street address of this user profile.", "type": "string" }, "city": { + "description": "The city for the user profile.", "type": "string" }, "company": { + "description": "That company that this user profile is associated with.", "type": "string" }, "country": { + "description": "Th country of this user profile.", "type": "string" }, "first_name": { + "description": "The first name of the user.", "type": "string" }, "last_name": { + "description": "The last name of the user.", "type": "string" }, "phone": { + "description": "The phone number for the user.", "type": "string" }, "state": { + "description": "The state for this user.", "type": "string" }, "website": { + "description": "The website associated with this user.", "type": "string" }, "zip": { + "description": "The zip code for this user.", "type": "string" } }, @@ -3079,12 +3124,20 @@ "title": "SendGrid V3 API", "version": "3.0" }, + "parameters": { + "trait:authorizationHeader:Authorization": { + "default": "Bearer <>", + "description": "", + "in": "header", + "name": "Authorization", + "required": true, + "type": "string" + } + }, "paths": { "/access_settings/activity": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "GET_access_settings-activity", "parameters": [ @@ -3112,14 +3165,6 @@ "ip": "1.1.1.1", "last_at": 1444406672, "location": "Australia" - }, - { - "allowed": false, - "auth_method": "basic", - "first_at": 1444087505, - "ip": "1.2.3.48", - "last_at": 1444087505, - "location": "Mukilteo, Washington" } ] } @@ -3127,50 +3172,32 @@ "schema": { "properties": { "result": { - "description": "An array containing the IPs that recently attempted to access your account.", "items": { "properties": { "allowed": { - "description": "Indicates if the IP address was granted access to the account.", "type": "boolean" }, "auth_method": { - "description": "The authentication method used when attempting access.", "type": "string" }, "first_at": { - "description": "A Unix timestamp indicating when the first access attempt was made.", "type": "integer" }, "ip": { - "description": "The IP addressed used during the access attempt.", "type": "string" }, "last_at": { - "description": "A Unix timestamp indicating when the most recent access attempt was made", "type": "integer" }, "location": { - "description": "The geographic location from which the access attempt originated.", "type": "string" } }, - "required": [ - "allowed", - "auth_method", - "first_at", - "ip", - "last_at", - "location" - ], "type": "object" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -3230,11 +3257,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -3256,9 +3279,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "GET_access_settings-whitelist", "parameters": [], @@ -3276,18 +3297,6 @@ "id": 1, "ip": "192.168.1.1/32", "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 2, - "ip": "192.168.1.2/32", - "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 3, - "ip": "192.168.1.3/32", - "updated_at": 1441824715 } ] } @@ -3295,40 +3304,26 @@ "schema": { "properties": { "result": { - "description": "An array listing all of your whitelisted IPs.", "items": { "properties": { "created_at": { - "description": "A Unix timestamp indicating when the IP was whitelisted.", "type": "integer" }, "id": { - "description": "The ID of the whitelisted IP.", "type": "integer" }, "ip": { - "description": "The whitelisted IP.", "type": "string" }, "updated_at": { - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated.", "type": "integer" } }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ], "type": "object" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -3415,18 +3410,6 @@ "id": 1, "ip": "192.168.1.1/32", "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 2, - "ip": "192.0.0.0/8", - "updated_at": 1441824715 - }, - { - "created_at": 1441824715, - "id": 3, - "ip": "192.168.1.3/32", - "updated_at": 1441824715 } ] } @@ -3434,40 +3417,26 @@ "schema": { "properties": { "result": { - "description": "An array listing all of your whitelisted IPs.", "items": { "properties": { "created_at": { - "description": "A Unix timestamp indicating when the IP was whitelisted.", "type": "integer" }, "id": { - "description": "The ID of the whitelisted IP.", "type": "integer" }, "ip": { - "description": "The whitelisted IP.", "type": "string" }, "updated_at": { - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated.", "type": "integer" } }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ], "type": "object" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -3493,28 +3462,14 @@ }, "/access_settings/whitelist/{rule_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a specific IP address from your IP whitelist.**\n\nWhen removing a specific IP address from your whitelist, you must include the ID in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "DELETE_access_settings-whitelist-rule_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -3536,9 +3491,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retreive a specific IP address that has been whitelisted.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "GET_access_settings-whitelist-rule_id", "parameters": [], @@ -3559,28 +3512,18 @@ "schema": { "properties": { "created_at": { - "description": "A Unix timestamp indicating when the IP was whitelisted.", "type": "integer" }, "id": { - "description": "The ID of the IP address.", "type": "integer" }, "ip": { - "description": "The IP address.", "type": "string" }, "updated_at": { - "description": "A Unix timestamp indicating when the IP address was last updated.", "type": "integer" } }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ], "type": "object" } } @@ -3613,14 +3556,19 @@ } ] }, - "/api_keys": { + "/alerts": { "get": { - "consumes": [ - "application/json" + "consumes": [], + "description": "**This endpoint allows you to retieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "GET_alerts", + "parameters": [ + { + "description": "", + "in": "header", + "name": "Authorization", + "type": "string" + } ], - "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).", - "operationId": "GET_api_keys", - "parameters": [], "produces": [ "application/json" ], @@ -3628,45 +3576,79 @@ "200": { "description": "", "examples": { - "application/json": { - "result": [ - { - "api_key_id": "some-apikey-id", - "name": "API Key Name" - }, - { - "api_key_id": "another-apikey-id", - "name": "API Key Name 2" - } - ] - } + "application/json": [ + { + "created_at": 1451498784, + "email_to": "reaper@example.com", + "id": 46, + "percentage": 90, + "type": "usage_limit", + "updated_at": 1451498784 + }, + { + "created_at": 1451498812, + "email_to": "reaper@example.com", + "frequency": "monthly", + "id": 47, + "type": "stats_notification", + "updated_at": 1451498812 + }, + { + "created_at": 1451520930, + "email_to": "someone@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451520930 + } + ] }, "schema": { - "properties": { - "result": { - "items": { - "$ref": "#/definitions/api_key_name_id" + "description": "The list of alerts.", + "items": { + "properties": { + "created_at": { + "description": "A Unix timestamp indicating when the alert was created.", + "type": "integer" }, - "type": "array" - } - }, - "type": "object" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "email_to": { + "description": "The email address that the alert will be sent to.", + "type": "string" + }, + "frequency": { + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\".", + "type": "string" + }, + "id": { + "description": "The ID of the alert.", + "type": "integer" + }, + "percentage": { + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.", + "type": "integer" + }, + "type": { + "description": "The type of alert.", + "enum": [ + "usage_limit", + "stats_notification" + ], + "type": "string" + }, + "updated_at": { + "description": "A Unix timestamp indicating when the alert was last modified.", + "type": "integer" } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + }, + "required": [ + "created_at", + "email_to", + "id", + "type" + ], + "type": "object" + }, + "type": "array" } } }, @@ -3675,11 +3657,14 @@ "Authorization": [] } ], - "summary": "Retrieve all API Keys belonging to the authenticated user", + "summary": "Retrieve all alerts", + "tags": [ + "Alerts" + ], "x-stoplight": { "afterScript": null, "beforeScript": null, - "id": "GET_apikeys", + "id": "GET_alerts", "mock": { "dynamic": false, "enabled": false, @@ -3693,94 +3678,474 @@ "consumes": [ "application/json" ], - "description": "**This enpoint allows you to create a new random API Key for the user.**\n\nA JSON request body containing a \"name\" property is required. If number of maximum keys is reached, HTTP 403 will be returned.\n\nThere is a limit of 100 API Keys on your account.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\nSee the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.", - "operationId": "create-api-keys", + "description": "**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "POST_alerts", "parameters": [ { "in": "body", "name": "body", "schema": { "example": { - "name": "My API Key", - "scopes": [ - "mail.send", - "alerts.create", - "alerts.read" - ] + "email_to": "eric.schallock@sendgrid.com", + "frequency": "daily", + "type": "stats_notification" }, "properties": { - "name": { - "description": "The name you will use to describe this API Key.", + "email_to": { + "description": "The email address the alert will be sent to.\nExample: test@example.com", "type": "string" }, - "scopes": { - "description": "The individual permissions that you are giving to this API Key.", - "items": { - "type": "string" - }, - "type": "array" + "frequency": { + "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily", + "type": "string" + }, + "percentage": { + "description": "Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90", + "type": "integer" + }, + "type": { + "description": "The type of alert you want to create. Can be either usage_alert or stats_notification.\nExample: usage_alert", + "type": "string" } }, "required": [ - "name" + "type", + "email_to" ], "type": "object" } + }, + { + "description": "", + "in": "header", + "name": "Authorization", + "type": "string" } ], "produces": [ - "application/json" + "application/json", + "text/plain" ], "responses": { "201": { "description": "", "examples": { - "application/json": { - "api_key": "SG.xxxxxxxx.yyyyyyyy", - "api_key_id": "xxxxxxxx", - "name": "My API Key", - "scopes": [ - "mail.send", - "alerts.create", - "alerts.read" - ] + "text/plain": { + "created_at": 1465595735, + "email_to": "eric.schallock@sendgrid.com", + "frequency": "daily", + "id": 304575, + "type": "stats_notification", + "updated_at": 1465595735 } }, "schema": { - "properties": { - "api_key": { - "type": "string" - }, - "api_key_id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "scopes": { - "items": { - "type": "string" - }, - "type": "array" - } - }, "type": "object" } - }, - "400": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": "name", - "message": "missing required argument" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Create a new Alert", + "tags": [ + "Alerts" + ], + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "POST_alerts", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + } + }, + "/alerts/{alert_id}": { + "delete": { + "consumes": [], + "description": "**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "DELETE_alerts-alert_id", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Delete an alert", + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "DELETE_alerts-alertid", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + }, + "get": { + "consumes": [], + "description": "**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "GET_alerts-alert_id", + "parameters": [ + { + "description": "", + "in": "header", + "name": "Authorization", + "type": "string" + } + ], + "produces": [ + "application/json", + "text/plain" + ], + "responses": { + "200": { + "description": "", + "examples": { + "text/plain": { + "created_at": 1465613735, + "email_to": "eric.schallock@sendgrid.com", + "frequency": "daily", + "id": 304575, + "type": "stats_notification", + "updated_at": 1465595735 + } + }, + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve a specific alert", + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "GET_alerts-alertid", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + }, + "parameters": [ + { + "description": "The ID of the alert you would like to retrieve.", + "in": "path", + "name": "alert_id", + "required": true, + "type": "integer" + } + ], + "patch": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "operationId": "PATCH_alerts-alert_id", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "example": { + "email_to": "test@example.com" + }, + "properties": { + "email_to": { + "description": "The new email address you want your alert to be sent to.\nExample: test@example.com", + "type": "string" + }, + "frequency": { + "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly", + "type": "string" + }, + "percentage": { + "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90", + "type": "integer" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "created_at": 1451520930, + "email_to": "test@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451522691 + } + }, + "schema": { + "properties": { + "created_at": { + "description": "A Unix timestamp indicating when the alert was created.", + "type": "integer" + }, + "email_to": { + "description": "The email address that the alert will be sent to.", + "type": "string" + }, + "frequency": { + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\".", + "type": "string" + }, + "id": { + "description": "The ID of the alert.", + "type": "integer" + }, + "percentage": { + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.", + "type": "integer" + }, + "type": { + "description": "The type of alert.", + "enum": [ + "usage_alert", + "stats_notification" + ], + "type": "string" + }, + "updated_at": { + "description": "A Unix timestamp indicating when the alert was last modified.", + "type": "integer" + } + }, + "required": [ + "created_at", + "email_to", + "id", + "type", + "updated_at" + ], + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Update an alert", + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "PATCH_alerts-alertid", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + } + }, + "/api_keys": { + "get": { + "consumes": [], + "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).", + "operationId": "GET_api_keys", + "parameters": [ + { + "in": "query", + "name": "limit", + "type": "integer" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "result": [ + { + "api_key_id": "some-apikey-id", + "name": "API Key Name" + }, + { + "api_key_id": "another-apikey-id", + "name": "API Key Name 2" + } + ] + } + }, + "schema": { + "properties": { + "result": { + "items": { + "$ref": "#/definitions/api_key_name_id" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve all API Keys belonging to the authenticated user", + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "GET_apikeys", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + }, + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This enpoint allows you to create a new random API Key for the user.**\n\nA JSON request body containing a \"name\" property is required. If number of maximum keys is reached, HTTP 403 will be returned.\n\nThere is a limit of 100 API Keys on your account.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\nSee the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.", + "operationId": "create-api-keys", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "example": { + "name": "My API Key", + "sample": "data", + "scopes": [ + "mail.send", + "alerts.create", + "alerts.read" + ] + }, + "properties": { + "name": { + "description": "The name you will use to describe this API Key.", + "type": "string" + }, + "sample": { + "type": "string" + }, + "scopes": { + "description": "The individual permissions that you are giving to this API Key.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "name" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", + "examples": { + "application/json": { + "api_key": "SG.xxxxxxxx.yyyyyyyy", + "api_key_id": "xxxxxxxx", + "name": "My API Key", + "scopes": [ + "mail.send", + "alerts.create", + "alerts.read" + ] + } + }, + "schema": { + "properties": { + "api_key": { + "type": "string" + }, + "api_key_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "scopes": { + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": "name", + "message": "missing required argument" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, "401": { @@ -3837,20 +4202,10 @@ }, "/api_keys/{api_key_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|", "operationId": "DELETE_api_keys-api_key_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -3900,9 +4255,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single api key.**\n\nIf the API Key ID does not exist an HTTP 404 will be returned.", "operationId": "GET_api_keys-api_key_id", "parameters": [], @@ -4185,10 +4538,8 @@ }, "/asm/groups": { "get": { - "consumes": [ - "application/json" - ], - "description": "**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.", + "consumes": [], + "description": "**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).\n\nSuppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content.", "operationId": "GET_asm-groups", "parameters": [ { @@ -4361,20 +4712,10 @@ }, "/asm/groups/{group_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a suppression group.**\n\nYou can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the \"one-click unsubscribe\" option on an email associated with a deleted group, that recipient will be added to the global suppression list.\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", "operationId": "DELETE_asm-groups-group_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -4405,9 +4746,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", "operationId": "GET_asm-groups-group_id", "parameters": [], @@ -4428,19 +4767,32 @@ } }, "schema": { - "allOf": [ - { - "$ref": "#/definitions/suppression_group" + "properties": { + "description": { + "description": "The description of the suppression group.", + "type": "string" }, - { - "properties": { - "unsubscribes": { - "description": "The unsubscribes associated with this group.", - "type": "integer" - } - } + "id": { + "description": "The ID of the suppression group.", + "type": "integer" + }, + "is_default": { + "description": "Indicates if this is the default suppression group.", + "type": "boolean" + }, + "last_email_sent_at": { + "description": "A unix timestamp indicating the last time this group was assigned to an email.", + "type": "null" + }, + "name": { + "description": "The name of the suppression group.", + "type": "string" + }, + "unsubscribes": { + "description": "The number of unsubscribes, or suppressions, in this group.", + "type": "integer" } - ], + }, "type": "object" } } @@ -4496,7 +4848,7 @@ }, "id": { "description": "The id of the suppression group.", - "type": "number" + "type": "integer" }, "is_default": { "description": "Indicates if the suppression group is set as the default group.", @@ -4549,30 +4901,119 @@ }, "/asm/groups/{group_id}/suppressions": { "get": { + "consumes": [], + "description": "**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", + "operationId": "GET_asm-groups-group_id-suppressions", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ + "example@example.com", + "example2@example.com" + ] + }, + "schema": { + "description": "The list of email addresses belonging to the given suppression group.", + "items": { + "type": "string" + }, + "type": "array" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve all suppressions for a suppression group", + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "GET_asm-groups-groupid-suppressions", + "mock": { + "dynamic": false, + "enabled": null, + "statusCode": null + }, + "public": true + } + }, + "parameters": [ + { + "description": "The id of the unsubscribe group that you are adding suppressions to.", + "in": "path", + "name": "group_id", + "required": true, + "type": "string" + } + ], + "post": { "consumes": [ "application/json" ], - "description": "**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", - "operationId": "GET_asm-groups-group_id-suppressions", - "parameters": [], + "description": "**This endpoint allows you to add email addresses to an unsubscribe group.**\n\nIf you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", + "operationId": "POST_asm-groups-group_id-suppressions", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "example": { + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] + }, + "properties": { + "recipient_emails": { + "description": "The email address that you want to add to the unsubscribe group.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "recipient_emails" + ], + "type": "object" + } + } + ], "produces": [ "application/json" ], "responses": { - "200": { + "201": { "description": "", "examples": { - "application/json": [ - "example@example.com", - "example2@example.com" - ] + "application/json": { + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] + } }, "schema": { - "description": "The list of email addresses belonging to the given suppression group.", - "items": { - "type": "string" + "properties": { + "recipient_emails": { + "description": "The email address that were added to the suppressions list.", + "items": { + "type": "string" + }, + "type": "array" + } }, - "type": "array" + "required": [ + "recipient_emails" + ], + "type": "object" } } }, @@ -4581,11 +5022,11 @@ "Authorization": [] } ], - "summary": "Retrieve all suppressions for a suppression group", + "summary": "Add suppressions to a suppression group", "x-stoplight": { "afterScript": null, "beforeScript": null, - "id": "GET_asm-groups-groupid-suppressions", + "id": "POST_asm-groups-groupid-suppressions", "mock": { "dynamic": false, "enabled": null, @@ -4593,10 +5034,12 @@ }, "public": true } - }, + } + }, + "/asm/groups/{group_id}/suppressions/search": { "parameters": [ { - "description": "The id of the suppression group that you are retrieving email addresses from.", + "description": "The ID of the suppression group that you would like to search.", "in": "path", "name": "group_id", "required": true, @@ -4607,8 +5050,8 @@ "consumes": [ "application/json" ], - "description": "**This endpoint allows you to add email addresses to an unsubscribe group.**\n\nIf you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", - "operationId": "POST_asm-groups-group_id-suppressions", + "description": "**This endpoint allows you to search a suppression group for multiple suppressions.**\n\nWhen given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", + "operationId": "POST_asm-groups-group_id-suppressions-search", "parameters": [ { "in": "body", @@ -4616,13 +5059,14 @@ "schema": { "example": { "recipient_emails": [ - "test1@example.com", - "test2@example.com" + "exists1@example.com", + "exists2@example.com", + "doesnotexists@example.com" ] }, "properties": { "recipient_emails": { - "description": "The email address that you want to add to the unsubscribe group.", + "description": "The list of email address that you want to search the suppression group for.", "items": { "type": "string" }, @@ -4640,20 +5084,20 @@ "application/json" ], "responses": { - "201": { + "200": { "description": "", "examples": { "application/json": { "recipient_emails": [ - "test1@example.com", - "test2@example.com" + "exists1@example.com", + "exists2@example.com" ] } }, "schema": { "properties": { "recipient_emails": { - "description": "The email address that were added to the suppressions list.", + "description": "The email address from your search that do exist in the suppression group.", "items": { "type": "string" }, @@ -4672,15 +5116,15 @@ "Authorization": [] } ], - "summary": "Add suppressions to a suppression group", + "summary": "Search for suppressions within a group", "x-stoplight": { "afterScript": null, "beforeScript": null, - "id": "POST_asm-groups-groupid-suppressions", + "id": "POST_asm-groups-groupid-suppressions-search", "mock": { "dynamic": false, - "enabled": null, - "statusCode": null + "enabled": false, + "statusCode": 200 }, "public": true } @@ -4688,27 +5132,14 @@ }, "/asm/groups/{group_id}/suppressions/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a suppressed email address from the given suppression group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.", "operationId": "DELETE_asm-groups-group_id-suppressions-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "null" - } + "description": "" } }, "security": [ @@ -4751,7 +5182,7 @@ "consumes": [ "application/json" ], - "description": "**This endpoint allows you to retrieve a list of all suppressions.**\n\nSuppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.", + "description": "**This endpoint allows you to retrieve a list of all suppressions.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", "operationId": "GET_asm-suppressions", "parameters": [], "produces": [ @@ -4924,27 +5355,14 @@ }, "/asm/suppressions/global/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "DELETE_asm-suppressions-global-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -4969,9 +5387,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "GET_asm-suppressions-global-email", "parameters": [], @@ -5019,7 +5435,7 @@ }, "parameters": [ { - "description": "The email address you want to remove from the global suppressions group.", + "description": "The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.", "in": "path", "name": "email", "required": true, @@ -5032,7 +5448,7 @@ "consumes": [ "application/json" ], - "description": "**This endpoint will return a list of all suppression groups, indicating if the given email address is suppressed for each group.**\n\nSuppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.", + "description": "**This endpoint returns the list of all groups that the given email address has been unsubscribed from.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", "operationId": "GET_asm-suppressions-email", "parameters": [], "produces": [ @@ -5147,9 +5563,7 @@ }, "/browsers/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by browser type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_browsers-stats", "parameters": [ @@ -5286,9 +5700,7 @@ }, "/campaigns": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "GET_campaigns", "parameters": [ @@ -5297,14 +5709,14 @@ "description": "The number of results you would like to receive at a time.", "in": "query", "name": "limit", - "type": "number" + "type": "integer" }, { "default": 0, "description": "The index of the first campaign to return, where 0 is the first campaign.", "in": "query", "name": "offset", - "type": "number" + "type": "integer" } ], "produces": [ @@ -5325,8 +5737,7 @@ "id": 986724, "ip_pool": "marketing", "list_ids": [ - 110, - 124 + 110 ], "plain_content": "Check out our spring line!", "segment_ids": [ @@ -5337,28 +5748,6 @@ "subject": "New Products for Spring!", "suppression_group_id": 42, "title": "March Newsletter" - }, - { - "categories": [ - "winter line" - ], - "custom_unsubscribe_url": "", - "html_content": "

Last call for winter clothes!

", - "id": 986723, - "ip_pool": "marketing", - "list_ids": [ - 110, - 124 - ], - "plain_content": "Last call for winter clothes!", - "segment_ids": [ - 110 - ], - "sender_id": 124451, - "status": "Sent", - "subject": "Final Winter Product Sale!", - "suppression_group_id": 42, - "title": "February Newsletter" } ] } @@ -5367,7 +5756,57 @@ "properties": { "result": { "items": { - "$ref": "#/definitions/campaign_response" + "properties": { + "categories": { + "items": { + "type": "string" + }, + "type": "array" + }, + "custom_unsubscribe_url": { + "type": "string" + }, + "html_content": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "ip_pool": { + "type": "string" + }, + "list_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "plain_content": { + "type": "string" + }, + "segment_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "sender_id": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "suppression_group_id": { + "type": "integer" + }, + "title": { + "type": "string" + } + }, + "type": "object" }, "type": "array" } @@ -5566,20 +6005,10 @@ }, "/campaigns/{campaign_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "DELETE_campaigns-campaign_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -5632,9 +6061,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "GET_campaigns-campaign_id", "parameters": [], @@ -5654,8 +6081,7 @@ "id": 986724, "ip_pool": "marketing", "list_ids": [ - 110, - 124 + 110 ], "plain_content": "Check out our spring line!", "segment_ids": [ @@ -5669,7 +6095,57 @@ } }, "schema": { - "$ref": "#/definitions/campaign_response" + "properties": { + "categories": { + "items": { + "type": "string" + }, + "type": "array" + }, + "custom_unsubscribe_url": { + "type": "string" + }, + "html_content": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "ip_pool": { + "type": "string" + }, + "list_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "plain_content": { + "type": "string" + }, + "segment_ids": { + "items": { + "type": "integer" + }, + "type": "array" + }, + "sender_id": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "suppression_group_id": { + "type": "integer" + }, + "title": { + "type": "string" + } + }, + "type": "object" } }, "401": { @@ -5725,7 +6201,7 @@ }, "parameters": [ { - "description": "The ID of the campaign that you would like to delete.", + "description": "The id of the campaign you would like to retrieve.", "in": "path", "name": "campaign_id", "required": true, @@ -5957,20 +6433,10 @@ }, "/campaigns/{campaign_id}/schedules": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "DELETE_campaigns-campaign_id-schedules", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -6045,9 +6511,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "GET_campaigns-campaign_id-schedules", "parameters": [], @@ -6438,20 +6902,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to immediately send a campaign at the time you make the API call.**\n\nNormally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "POST_campaigns-campaign_id-schedules-now", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -6707,10 +7161,8 @@ } }, "/categories": { - "get": { - "consumes": [ - "application/json" - ], + "get": { + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all of your categories.**\n\nCategories can help organize your email analytics by enabling you to \u201ctag\u201d emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).", "operationId": "GET_categories", "parameters": [ @@ -6831,9 +7283,7 @@ }, "/categories/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). ", "operationId": "GET_categories-stats", "parameters": [ @@ -7028,9 +7478,7 @@ }, "/categories/stats/sums": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). ", "operationId": "GET_categories-stats-sums", "parameters": [ @@ -7255,9 +7703,7 @@ }, "/clients/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_clients-stats", "parameters": [ @@ -7357,9 +7803,7 @@ }, "/clients/{client_type}/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Client Types\n- phone\n- tablet\n- webmail\n- desktop\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_clients-client_type-stats", "parameters": [ @@ -7470,9 +7914,7 @@ }, "/contactdb/custom_fields": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all custom fields.** \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-custom_fields", "parameters": [], @@ -7671,20 +8113,10 @@ }, "/contactdb/custom_fields/{custom_field_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "DELETE_contactdb-custom_fields-custom_field_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -7769,9 +8201,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-custom_fields-custom_field_id", "parameters": [], @@ -7886,7 +8316,7 @@ 4 ], "items": { - "type": "number" + "type": "integer" }, "type": "array" } @@ -7957,9 +8387,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-lists", "parameters": [], @@ -8128,9 +8556,7 @@ }, "/contactdb/lists/{list_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific recipient list with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-lists-list_id", "parameters": [ @@ -8143,13 +8569,6 @@ "in": "query", "name": "delete_contacts", "type": "boolean" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [ @@ -8233,9 +8652,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "This endpoint allows you to retrieve a single recipient list.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-lists-list_id", "parameters": [ @@ -8243,7 +8660,7 @@ "description": "The ID of the list to retrieve.", "in": "query", "name": "list_id", - "type": "number" + "type": "integer" } ], "produces": [ @@ -8349,7 +8766,7 @@ "in": "query", "name": "list_id", "required": true, - "type": "number" + "type": "integer" }, { "in": "body", @@ -8434,9 +8851,7 @@ }, "/contactdb/lists/{list_id}/recipients": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all recipients on the list with the given ID.** \n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-lists-list_id-recipients", "parameters": [ @@ -8459,7 +8874,7 @@ "in": "query", "name": "list_id", "required": true, - "type": "number" + "type": "integer" } ], "produces": [ @@ -8723,9 +9138,7 @@ }, "/contactdb/lists/{list_id}/recipients/{recipient_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a single recipient from a list.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-lists-list_id-recipients-recipient_id", "parameters": [ @@ -8734,21 +9147,14 @@ "in": "query", "name": "list_id", "required": true, - "type": "number" + "type": "integer" }, { "description": "The ID of the recipient to take off the list.", "in": "query", "name": "recipient_id", "required": true, - "type": "number" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } + "type": "integer" } ], "produces": [ @@ -8853,20 +9259,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to add a single recipient to a list.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "POST_contactdb-lists-list_id-recipients-recipient_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -9040,9 +9436,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**\n\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients", "parameters": [ @@ -9259,6 +9653,9 @@ ], "items": { "properties": { + "age": { + "type": "integer" + }, "email": { "description": "The email address of the recipient.", "format": "email", @@ -9371,9 +9768,7 @@ }, "/contactdb/recipients/billable_count": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**\n\nYou are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients-billable_count", "parameters": [], @@ -9431,9 +9826,7 @@ }, "/contactdb/recipients/count": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-recipients-count", "parameters": [], @@ -9494,9 +9887,7 @@ }, "/contactdb/recipients/search": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 02 Feb 2015 23:59:59 GMT.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-recipients-search", "parameters": [ @@ -9504,6 +9895,11 @@ "in": "query", "name": "{field_name}", "type": "string" + }, + { + "in": "query", + "name": "%7Bfield_name%7D", + "type": "string" } ], "produces": [ @@ -9609,20 +10005,10 @@ }, "/contactdb/recipients/{recipient_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a single recipient with the given ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-recipients-recipient_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -9701,9 +10087,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single recipient by ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients-recipient_id", "parameters": [], @@ -9776,9 +10160,7 @@ }, "/contactdb/recipients/{recipient_id}/lists": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the lists that a given recipient belongs to.**\n\nEach recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "GET_contactdb-recipients-recipient_id-lists", "parameters": [], @@ -9890,9 +10272,7 @@ }, "/contactdb/reserved_fields": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "GET_contactdb-reserved_fields", "parameters": [], @@ -10000,9 +10380,7 @@ }, "/contactdb/segments": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your segments.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "GET_contactdb-segments", "parameters": [], @@ -10269,9 +10647,7 @@ }, "/contactdb/segments/{segment_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a segment from your recipients database.**\n\nYou also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "DELETE_contactdb-segments-segment_id", "parameters": [ @@ -10280,13 +10656,6 @@ "in": "query", "name": "delete_contacts", "type": "boolean" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [ @@ -10371,9 +10740,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single segment with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "GET_contactdb-segments-segment_id", "parameters": [ @@ -10382,7 +10749,7 @@ "in": "query", "name": "segment_id", "required": true, - "type": "number" + "type": "integer" } ], "produces": [ @@ -10658,9 +11025,7 @@ }, "/contactdb/segments/{segment_id}/recipients": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", "operationId": "GET_contactdb-segments-segment_id-recipients", "parameters": [ @@ -10781,9 +11146,7 @@ }, "/devices/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_devices-stats", "parameters": [ @@ -11269,9 +11632,7 @@ }, "/geo/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by country and state/province.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_geo-stats", "parameters": [ @@ -11831,9 +12192,7 @@ }, "/ips": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all assigned and unassigned IPs.**\n\nResponse includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "GET_ips", "parameters": [ @@ -11980,9 +12339,7 @@ }, "/ips/assigned": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve only assigned IP addresses.**\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "GET_ips-assigned", "parameters": [], @@ -12065,9 +12422,7 @@ }, "/ips/pools": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retreive all of your IP pools.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "GET_ips-pools", "parameters": [], @@ -12185,20 +12540,10 @@ }, "/ips/pools/{pool_name}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete an IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "DELETE_ips-pools-pool_name", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -12246,9 +12591,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to list all of the IP addresses that are in a specific IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "GET_ips-pools-pool_name", "parameters": [], @@ -12571,20 +12914,10 @@ }, "/ips/pools/{pool_name}/ips/{ip}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an IP address from an IP pool.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "DELETE_ips-pools-pool_name-ips-ip", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -12650,9 +12983,7 @@ }, "/ips/warmup": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "GET_ips-warmup", "parameters": [], @@ -12798,20 +13129,10 @@ }, "/ips/warmup/{ip_address}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "DELETE_ips-warmup-ip_address", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -12876,9 +13197,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the warmup status for a specific IP address.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "GET_ips-warmup-ip_address", "parameters": [], @@ -12957,9 +13276,7 @@ }, "/ips/{ip_address}": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to see which IP pools a particular IP address has been added to.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "GET_ips-ip_address", "parameters": [], @@ -13069,20 +13386,10 @@ "/mail/batch": { "parameters": [], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.**\n\nIf you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", "operationId": "POST_mail-batch", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -13139,9 +13446,7 @@ }, "/mail/batch/{batch_id}": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate a batch ID.**\n\nIf you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", "operationId": "GET_mail-batch-batch_id", "parameters": [], @@ -13220,14 +13525,14 @@ } ] }, - "/mail/send/beta": { + "/mail/send": { "parameters": [], "post": { "consumes": [ "application/json" ], "description": "This endpoint allows you to send email over SendGrid\u2019s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n* Top level parameters are referred to as \"global\".\n* Individual fields within the personalizations array will override any other global, or \u201cmessage level\u201d, parameters that are defined outside of personalizations.\n\nFor an overview of the v3 Mail Send endpoint, please visit our [v3 API Reference](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html)\n\nFor more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html).", - "operationId": "POST_mail-send-beta", + "operationId": "POST_mail-send", "parameters": [ { "in": "body", @@ -13260,7 +13565,7 @@ "content": [ { "type": "text/html", - "value": "

Hello, world!

" + "value": "

Hello, world!

" } ], "custom_args": { @@ -13322,13 +13627,8 @@ "send_at": 1409348513, "subject": "Hello, World!", "substitutions": { - "sub": { - "%name%": [ - "John", - "Jane", - "Sam" - ] - } + "id": "substitutions", + "type": "object" }, "to": [ { @@ -13649,7 +13949,7 @@ ], "type": "object" }, - "maxItems": 100, + "maxItems": 1000, "type": "array", "uniqueItems": false }, @@ -13769,7 +14069,6 @@ "required": [ "personalizations", "from", - "reply_to", "subject", "content" ], @@ -13812,14 +14111,14 @@ "Authorization": [] } ], - "summary": "v3 Mail Send Beta", + "summary": "v3 Mail Send", "tags": [ "Mail Send" ], "x-stoplight": { "afterScript": null, "beforeScript": null, - "id": "POST_mail-send-beta", + "id": "POST_mail-send", "mock": { "dynamic": false, "enabled": false, @@ -13831,9 +14130,7 @@ }, "/mail_settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all mail settings.**\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings", "parameters": [ @@ -13985,9 +14282,7 @@ }, "/mail_settings/address_whitelist": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current email address whitelist settings.**\n\nThe address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain \u201cexample.com,\u201d and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-address_whitelist", "parameters": [], @@ -14104,9 +14399,7 @@ }, "/mail_settings/bcc": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current BCC mail settings.**\n\nWhen the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-bcc", "parameters": [], @@ -14203,9 +14496,7 @@ }, "/mail_settings/bounce_purge": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current bounce purge settings.**\n\nThis setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-bounce_purge", "parameters": [], @@ -14305,9 +14596,7 @@ }, "/mail_settings/footer": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Footer mail settings.**\n\nThe footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-footer", "parameters": [], @@ -14407,9 +14696,7 @@ }, "/mail_settings/forward_bounce": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current bounce forwarding mail settings.**\n\nActivating this setting allows you to specify an email address to which bounce reports are forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-forward_bounce", "parameters": [], @@ -14506,9 +14793,7 @@ }, "/mail_settings/forward_spam": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Forward Spam mail settings.**\n\nEnabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-forward_spam", "parameters": [], @@ -14604,10 +14889,8 @@ } }, "/mail_settings/plain_content": { - "get": { - "consumes": [ - "application/json" - ], + "get": { + "consumes": [], "description": "**This endpoint allows you to retrieve your current Plain Content mail settings.**\n\nThe plain content setting will automatically convert any plain text emails that you send to HTML before sending.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-plain_content", "parameters": [], @@ -14719,9 +15002,7 @@ }, "/mail_settings/spam_check": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Spam Checker mail settings.**\n\nThe spam checker filter notifies you when emails are detected that exceed a predefined spam threshold.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-spam_check", "parameters": [], @@ -14838,9 +15119,7 @@ }, "/mail_settings/template": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "GET_mail_settings-template", "parameters": [], @@ -14924,12 +15203,18 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if the legacy email template mail setting is enabled.", "type": "boolean" }, "html_content": { + "description": "The HTML content of your legacy email template.", "type": "string" } }, + "required": [ + "enabled", + "html_content" + ], "type": "object" } } @@ -14955,9 +15240,7 @@ }, "/mailbox_providers/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "operationId": "GET_mailbox_providers-stats", "parameters": [ @@ -15700,9 +15983,7 @@ }, "/partner_settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all partner settings that you can enable.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).", "operationId": "GET_partner_settings", "parameters": [ @@ -15796,9 +16077,7 @@ }, "/partner_settings/new_relic": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html).", "operationId": "GET_partner_settings-new_relic", "parameters": [], @@ -15912,9 +16191,7 @@ }, "/scopes": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys can be used to authenticate the use of [SendGrid\u2019s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). ", "operationId": "GET_scopes", "parameters": [], @@ -16017,9 +16294,7 @@ }, "/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your global email statistics between a given date range.**\n\nParent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.", "operationId": "GET_stats", "parameters": [ @@ -16370,9 +16645,7 @@ }, "/subusers": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", "operationId": "GET_subusers", "parameters": [ @@ -16386,13 +16659,13 @@ "description": "The number of results you would like to get in each request.", "in": "query", "name": "limit", - "type": "number" + "type": "integer" }, { "description": "The number of subusers to skip.", "in": "query", "name": "offset", - "type": "number" + "type": "integer" } ], "produces": [ @@ -16627,9 +16900,7 @@ }, "/subusers/reputations": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "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 effect your sender rating.\n\nThis endpoint allows you to request the reputations for your subusers.", "operationId": "GET_subusers-reputations", "parameters": [ @@ -16677,12 +16948,6 @@ }, "type": "array" } - }, - "401": { - "description": "", - "schema": { - "type": "object" - } } }, "security": [ @@ -16710,9 +16975,7 @@ }, "/subusers/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "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.\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-stats", "parameters": [ @@ -17074,9 +17337,7 @@ }, "/subusers/stats/monthly": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\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\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-stats-monthly", "parameters": [ @@ -17222,9 +17483,7 @@ }, "/subusers/stats/sums": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**\n\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-stats-sums", "parameters": [ @@ -17328,20 +17587,10 @@ }, "/subusers/{subuser_name}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", "operationId": "DELETE_subusers-subuser_name", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -17349,6 +17598,7 @@ "204": { "description": "", "schema": { + "properties": {}, "type": "object" } }, @@ -17426,6 +17676,7 @@ "204": { "description": "", "schema": { + "properties": {}, "type": "object" } }, @@ -17518,6 +17769,7 @@ "in": "body", "name": "body", "schema": { + "description": "The IP addresses you would like to assign to the subuser.", "example": [ "127.0.0.1" ], @@ -17545,6 +17797,7 @@ "schema": { "properties": { "ips": { + "description": "The IP addresses that are assigned to the subuser.", "items": { "format": "ipv4", "type": "string" @@ -17588,20 +17841,10 @@ }, "/subusers/{subuser_name}/monitor": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", "operationId": "DELETE_subusers-subuser_name-monitor", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -17609,6 +17852,7 @@ "204": { "description": "", "schema": { + "properties": {}, "type": "object" } }, @@ -17659,9 +17903,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", "operationId": "GET_subusers-subuser_name-monitor", "parameters": [], @@ -17916,9 +18158,7 @@ }, "/subusers/{subuser_name}/stats/monthly": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\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\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", "operationId": "GET_subusers-subuser_name-stats-monthly", "parameters": [ @@ -17955,7 +18195,7 @@ "in": "query", "name": "limit", "required": false, - "type": "number" + "type": "integer" }, { "default": 0, @@ -18074,11 +18314,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -18103,9 +18339,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "GET_suppression-blocks", "parameters": [ @@ -18207,28 +18441,14 @@ }, "/suppression/blocks/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "DELETE_suppression-blocks-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "summary": "Delete a specific block", @@ -18248,9 +18468,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "GET_suppression-blocks-email", "parameters": [], @@ -18417,9 +18635,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of your bounces.**\n\nBounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)", "operationId": "GET_suppression-bounces", "parameters": [ @@ -18427,19 +18643,13 @@ "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", "in": "query", "name": "start_time", - "type": "number" + "type": "integer" }, { "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", "in": "query", "name": "end_time", - "type": "number" - }, - { - "description": "", - "in": "header", - "name": "Allow", - "type": "string" + "type": "integer" } ], "produces": [ @@ -18527,9 +18737,7 @@ }, "/suppression/bounces/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove an email address from your bounce list.**\n\nBounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)", "operationId": "DELETE_suppression-bounces-email", "parameters": [ @@ -18540,13 +18748,6 @@ "name": "email_address", "required": true, "type": "string" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [ @@ -18598,9 +18799,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific bounce for a given email address.**\n\nBounces are messages that are returned to the server that sent it.\n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)", "operationId": "GET_suppression-bounces-email", "parameters": [], @@ -18711,11 +18910,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -18737,9 +18932,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all invalid email addresses.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "GET_suppression-invalid_emails", "parameters": [ @@ -18838,28 +19031,14 @@ }, "/suppression/invalid_emails/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a specific email address from the invalid email address list.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "DELETE_suppression-invalid_emails-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "summary": "Delete a specific invalid email", @@ -18876,9 +19055,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific invalid email addresses.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "GET_suppression-invalid_emails-email", "parameters": [], @@ -18939,7 +19116,7 @@ }, "parameters": [ { - "description": "The invalid email address that you want to remove.", + "description": "The specific email address of the invalid email entry that you want to retrieve.", "in": "path", "name": "email", "required": true, @@ -18949,28 +19126,14 @@ }, "/suppression/spam_report/{email}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "DELETE_suppression-spam_report-email", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -18992,9 +19155,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "GET_suppression-spam_report-email", "parameters": [], @@ -19060,7 +19221,7 @@ }, "parameters": [ { - "description": "The email address for the spam report that you want to delete.", + "description": "The email address of a specific spam report that you want to retrieve.", "in": "path", "name": "email", "required": true, @@ -19107,11 +19268,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -19133,9 +19290,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all spam reports.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "GET_suppression-spam_reports", "parameters": [ @@ -19233,9 +19388,7 @@ }, "/suppression/unsubscribes": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "GET_suppression-unsubscribes", "parameters": [ @@ -19329,9 +19482,7 @@ }, "/templates": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all transactional templates.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).", "operationId": "GET_templates", "parameters": [], @@ -19441,27 +19592,14 @@ }, "/templates/{template_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", "operationId": "DELETE_templates-template_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -19483,9 +19621,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a single transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", "operationId": "GET_templates-template_id", "parameters": [], @@ -19682,27 +19818,14 @@ }, "/templates/{template_id}/versions/{version_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete one of your transactional template versions.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "DELETE_templates-template_id-versions-version_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "null" - } + "description": "" } }, "security": [ @@ -19724,9 +19847,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific version of a template.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "GET_templates-template_id-versions-version_id", "parameters": [], @@ -19921,20 +20042,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to activate a version of one of your templates.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "POST_templates-template_id-versions-version_id-activate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -19996,9 +20107,7 @@ }, "/tracking_settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings", "parameters": [ @@ -20087,9 +20196,7 @@ }, "/tracking_settings/click": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current click tracking setting.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-click", "parameters": [], @@ -20219,9 +20326,7 @@ }, "/tracking_settings/google_analytics": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current setting for Google Analytics.**\n\nFor more information about using Google Analytics, please refer to [Google\u2019s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on [\"Best Practices for Campaign Building\"](https://support.google.com/analytics/answer/1037445).\n\nWe default the settings to Google\u2019s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html).\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-google_analytics", "parameters": [], @@ -20330,9 +20435,7 @@ }, "/tracking_settings/open": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current settings for open tracking.**\n\nOpen Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid\u2019s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-open", "parameters": [], @@ -20450,9 +20553,7 @@ }, "/tracking_settings/subscription": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "GET_tracking_settings-subscription", "parameters": [], @@ -20561,9 +20662,7 @@ }, "/user/account": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your user account details.**\n\nYour user's account information includes the user's account type and reputation.\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-account", "parameters": [], @@ -20628,9 +20727,7 @@ }, "/user/credits": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the current credit balance for your account.**\n\nYour monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html).", "operationId": "GET_user-credits", "parameters": [], @@ -20720,9 +20817,7 @@ }, "/user/email": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the email address currently on file for your account.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-email", "parameters": [], @@ -20877,11 +20972,7 @@ "produces": [], "responses": { "200": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } + "description": "" } }, "security": [ @@ -20908,9 +20999,7 @@ }, "/user/profile": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-profile", "parameters": [], @@ -20997,12 +21086,6 @@ "title": "GET User Profile response", "type": "object" } - }, - "401": { - "description": "", - "schema": { - "type": "object" - } } }, "security": [ @@ -21045,12 +21128,6 @@ "last_name": "User" } } - }, - { - "description": "You can enter a subuser name as the value for this header, in order to update the subuser's profile.", - "in": "header", - "name": "on-behalf-of", - "type": "string" } ], "produces": [ @@ -21119,9 +21196,7 @@ }, "/user/scheduled_sends": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all cancel/paused scheduled send information.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "operationId": "GET_user-scheduled_sends", "parameters": [], @@ -21298,20 +21373,10 @@ }, "/user/scheduled_sends/{batch_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete the cancellation/pause of a scheduled send.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "operationId": "DELETE_user-scheduled_sends-batch_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -21374,9 +21439,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "operationId": "GET_user-scheduled_sends-batch_id", "parameters": [], @@ -21560,9 +21623,7 @@ }, "/user/settings/enforced_tls": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current Enforced TLS settings.**\n\nThe Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS.\n\n**Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with \u201cTLS required but not supported\u201d as the description.", "operationId": "GET_user-settings-enforced_tls", "parameters": [], @@ -21697,9 +21758,7 @@ }, "/user/username": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current account username.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", "operationId": "GET_user-username", "parameters": [], @@ -21829,9 +21888,7 @@ }, "/user/webhooks/event/settings": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid\u2019s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", "operationId": "GET_user-webhooks-event-settings", "parameters": [], @@ -21994,10 +22051,7 @@ "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -22027,7 +22081,7 @@ "consumes": [ "application/json" ], - "description": "**This endpoint allows you to retrieve your current inbound parse webhook settings.**\n\nSendGrid can parse the attachments and contents of incoming emails. The Parse API will POST the parsed email to a URL that you specify. For more information, see our Inbound [Parse Webhook documentation](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "description": "**This endpoint allows you to retrieve all of your current inbound parse settings.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", "operationId": "GET_user-webhooks-parse-settings", "parameters": [], "produces": [ @@ -22040,10 +22094,10 @@ "application/json": { "result": [ { - "hostname": "example.com", - "send_raw": false, - "spam_check": false, - "url": "http://example.com/example" + "hostname": "mail.mydomain.com", + "send_raw": true, + "spam_check": true, + "url": "http://mydomain.com/parse" } ] } @@ -22051,40 +22105,13 @@ "schema": { "properties": { "result": { - "description": "The array containing the parse webhook settings.", + "description": "The list of your current inbound parse settings.", "items": { - "properties": { - "hostname": { - "description": "The hostname of the URL where you would like your parsed emails to be posted.", - "type": "string" - }, - "send_raw": { - "description": "Indicates if the raw content that was parsed will be posted.", - "type": "boolean" - }, - "spam_check": { - "description": "Indicates if the parsed content will be checked for spam.", - "type": "boolean" - }, - "url": { - "description": "The URL where you want your parsed emails to be posted.", - "type": "string" - } - }, - "required": [ - "hostname", - "url", - "spam_check", - "send_raw" - ], - "type": "object" + "$ref": "#/definitions/parse-setting" }, "type": "array" } }, - "required": [ - "result" - ], "type": "object" } } @@ -22094,14 +22121,236 @@ "Authorization": [] } ], - "summary": "Retrieve Parse Webhook settings", - "tags": [ - "Webhooks" - ], + "summary": "Retrieve all parse settings", + "tags": [ + "Settings - Inbound Parse" + ], + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "GET_user-webhooks-parse-settings", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + }, + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to create a new inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "POST_user-webhooks-parse-settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/parse-setting", + "example": { + "hostname": "myhostname.com", + "send_raw": false, + "spam_check": true, + "url": "http://email.myhosthame.com" + } + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", + "examples": { + "application/json": { + "hostname": "myhostname.com", + "send_raw": true, + "spam_check": false, + "url": "http://email.myhostname.com" + } + }, + "schema": { + "$ref": "#/definitions/parse-setting" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Create a parse setting", + "tags": [ + "Settings - Inbound Parse" + ], + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "POST_user-webhooks-parse-settings", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + } + }, + "/user/webhooks/parse/settings/{hostname}": { + "delete": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to delete a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "DELETE_user-webhooks-parse-settings-hostname", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Delete a parse setting", + "tags": [ + "Settings - Inbound Parse" + ], + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "DELETE_user-webhooks-parse-settings-hostname", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + }, + "get": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to retrieve a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "GET_user-webhooks-parse-settings-hostname", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "hostname": "mail.mydomain.com", + "send_raw": true, + "spam_check": true, + "url": "http://mydomain.com/parse" + } + }, + "schema": { + "$ref": "#/definitions/parse-setting" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Retrieve a specific parse setting", + "tags": [ + "Settings - Inbound Parse" + ], + "x-stoplight": { + "afterScript": null, + "beforeScript": null, + "id": "GET_user-webhooks-parse-settings-hostname", + "mock": { + "dynamic": false, + "enabled": false, + "statusCode": 200 + }, + "public": true + } + }, + "parameters": [ + { + "description": "The hostname associated with the inbound parse setting that you want to delete.", + "in": "path", + "name": "hostname", + "required": true, + "type": "string" + } + ] + }, + "/user/webhooks/parse/settings/{hostname}/": { + "parameters": [ + { + "description": "The hostname associated with the specific inbound parse setting that you want to update.", + "in": "path", + "name": "hostname", + "required": true, + "type": "string" + } + ], + "patch": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to update a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", + "operationId": "PATCH_user-webhooks-parse-settings-hostname", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/parse-setting", + "example": { + "send_raw": true, + "spam_check": false, + "url": "http://newdomain.com/parse" + } + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "hostname": "mail.mydomain.com", + "send_raw": true, + "spam_check": true, + "url": "http://mydomain.com/parse" + } + }, + "schema": { + "$ref": "#/definitions/parse-setting" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "Update a parse setting", "x-stoplight": { "afterScript": null, "beforeScript": null, - "id": "GET_user-webhooks-parse-settings", + "id": "PATCH_user-webhooks-parse-settings-hostname-", "mock": { "dynamic": false, "enabled": false, @@ -22109,14 +22358,11 @@ }, "public": true } - }, - "parameters": [] + } }, "/user/webhooks/parse/stats": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the statistics for your Parse Webhook useage.**\n\nSendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments.\n\nThere are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries).", "operationId": "GET_user-webhooks-parse-stats", "parameters": [ @@ -22546,9 +22792,7 @@ }, "/whitelabel/domains": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a list of all domain whitelabels you have created.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", "operationId": "GET_whitelabel-domains", "parameters": [ @@ -22979,9 +23223,7 @@ }, "/whitelabel/domains/default": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the default whitelabel for a domain.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| domain | string |The domain to find a default domain whitelabel for. |", "operationId": "GET_whitelabel-domains-default", "parameters": [], @@ -23021,27 +23263,14 @@ }, "/whitelabel/domains/subuser": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to disassociate a specific whitelabel from a subuser.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n| username | string | required | Username for the subuser to find associated whitelabels for. |", "operationId": "DELETE_whitelabel-domains-subuser", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -23066,9 +23295,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| username | string | Username of the subuser to find associated whitelabels for. |", "operationId": "GET_whitelabel-domains-subuser", "parameters": [], @@ -23149,27 +23376,14 @@ }, "/whitelabel/domains/{domain_id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a domain whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", "operationId": "DELETE_whitelabel-domains-domain_id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -23191,9 +23405,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific domain whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", "operationId": "GET_whitelabel-domains-domain_id", "parameters": [], @@ -23226,7 +23438,15 @@ "public": true } }, - "parameters": [], + "parameters": [ + { + "description": "The id of the domain whitelabel.", + "in": "path", + "name": "domain_id", + "required": true, + "type": "number" + } + ], "patch": { "consumes": [ "application/json" @@ -23518,20 +23738,10 @@ }, "/whitelabel/domains/{id}/ips/{ip}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to remove a domain's IP address from that domain's whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain whitelabel to delete the IP from. |\n| ip | string | IP to remove from the domain whitelabel. |", "operationId": "DELETE_whitelabel-domains-id-ips-ip", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -23630,20 +23840,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer |ID of the domain whitelabel to validate. |", "operationId": "POST_whitelabel-domains-id-validate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -23747,12 +23947,6 @@ "type": "object" } }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object" - } - }, "500": { "description": "", "examples": { @@ -23810,9 +24004,7 @@ }, "/whitelabel/ips": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.**\n\nYou may include a search key by using the \"ip\" parameter. This enables you to perform a prefix search for a given IP segment (e.g. \"192.\").\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "GET_whitelabel-ips", "parameters": [ @@ -24017,20 +24209,10 @@ }, "/whitelabel/ips/{id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "DELETE_whitelabel-ips-id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -24094,9 +24276,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "GET_whitelabel-ips-id", "parameters": [], @@ -24193,7 +24373,7 @@ }, "parameters": [ { - "description": "The id of the IP whitelabel that you would like to retrieve.", + "description": "The id of the IP whitelabel that you want to delete.", "in": "path", "name": "id", "required": true, @@ -24211,20 +24391,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "POST_whitelabel-ips-id-validate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -24393,9 +24563,7 @@ }, "/whitelabel/links": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve all link whitelabels.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links", "parameters": [ @@ -24611,9 +24779,7 @@ }, "/whitelabel/links/default": { "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the default link whitelabel.**\n\nDefault link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order:\n
    \n
  • Validated link whitelabels marked as \"default\"
    • \n
  • Legacy link whitelabels (migrated from the whitelabel wizard)
    • \n
  • Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)
    • \n
\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links-default", "parameters": [ @@ -24686,9 +24852,7 @@ }, "/whitelabel/links/subuser": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to disassociate a link whitelabel from a subuser.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "DELETE_whitelabel-links-subuser", "parameters": [ @@ -24698,22 +24862,12 @@ "name": "username", "required": true, "type": "string" - }, - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } } ], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -24738,9 +24892,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve the associated link whitelabel for a subuser.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links-subuser", "parameters": [ @@ -24814,27 +24966,14 @@ }, "/whitelabel/links/{id}": { "delete": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to delete a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "DELETE_whitelabel-links-id", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [], "responses": { "204": { - "description": "", - "schema": { - "type": "object" - } + "description": "" } }, "security": [ @@ -24859,9 +24998,7 @@ } }, "get": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to retrieve a specific link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "GET_whitelabel-links-id", "parameters": [], @@ -24925,7 +25062,7 @@ }, "parameters": [ { - "description": "The id of the link whitelabel you want to retrieve.", + "description": "The id of the link whitelabel that you want to delete.", "in": "path", "name": "id", "required": true, @@ -25030,20 +25167,10 @@ } ], "post": { - "consumes": [ - "application/json" - ], + "consumes": [], "description": "**This endpoint allows you to validate a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "POST_whitelabel-links-id-validate", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "type": "null" - } - } - ], + "parameters": [], "produces": [ "application/json" ], @@ -25148,12 +25275,6 @@ "type": "object" } }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object" - } - }, "500": { "description": "", "examples": { @@ -25320,8 +25441,8 @@ }, "swagger": "2.0", "x-stoplight": { - "afterScript": "function (ctx, request, response) {\n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint AFTER scripts will not be run!\n SL.runEndpoint();\n \n// if (response.body.get().count() > 1) {\n// request.hijack(200, 'application/json', {foo: 'bear'})\n// }\n\n \n //make this always available\n //SL.utilities.Audit_LogDataInResponse(ctx, request, response);\n \n //if (request.url.query.get('test')) {\n // SL.utilities.RunSpecifiedTests(ctx, request, response);\n //}\n \n // ELMER: Remove this\n // response.validate();\n // if (request.valid.get() && response.valid.get()) {\n // ctx.log.set(false);\n // } else {\n // ctx.log.set(true);\n // }\n}", - "beforeScript": "function (ctx, request) {\n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint before scripts will not be run!\n SL.runEndpoint();\n \n //adds the Accept header to every request\n // request.header.set(\"accept\", \"application/json\")\n \n //request.header.set(\"foo\", \"bear\");\n //request.header.add(\"bar\", \"cat\");\n\n if (request.url.query.get('accept')) {\n request.header.set('Accept', 'this is a bad header');\n }\n \n if (request.url.query.get('behalf')) {\n request.header.set('on-behalf-of', 'subuser2');\n }\n \n // For example, adding ?mock=200 to a request url will enable mocking,\n // using the example endpoint response for the 200 status code.\n // var mock = request.url.query.get(\"mock\")\n // if (mock) {\n // ctx.mock.set(true, mock)\n //}\n \n // For example, adding the header X-Mock: 200 will enable mocking,\n // using the example endpoint response for the 200 status code.\n var mock = request.header.get(\"X-Mock\");\n if (mock) {\n\t ctx.mock.set(true, mock);\n }\n \n // ELMER: Remove this\n // request.validate();\n}", + "afterScript": "function (ctx, request, response) {\n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint AFTER scripts will not be run!\n SL.runEndpoint();\n \n// if (response.body.get().count() > 1) {\n// request.hijack(200, 'application/json', {foo: 'bear'})\n// }\n\n \n //make this always available\n //SL.utilities.Audit_LogDataInResponse(ctx, request, response);\n \n //if (request.url.query.get('test')) {\n // SL.utilities.RunSpecifiedTests(ctx, request, response);\n //}\n \n // ELMER: Remove this, it logs only DELETE calls\n // if (JSON.parse(request.header.get('X-Mock')) == response.statusCode.get()) {\n // ctx.log.set(false);\n // } else {\n // ctx.log.set(true);\n //}\n}", + "beforeScript": "function (ctx, request) {\n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint before scripts will not be run!\n SL.runEndpoint();\n \n //adds the Accept header to every request\n // request.header.set(\"accept\", \"application/json\")\n \n //request.header.set(\"foo\", \"bear\");\n //request.header.add(\"bar\", \"cat\");\n\n if (request.url.query.get('accept')) {\n request.header.set('Accept', 'this is a bad header');\n }\n \n if (request.url.query.get('behalf')) {\n request.header.set('on-behalf-of', 'subuser2');\n }\n \n // For example, adding ?mock=200 to a request url will enable mocking,\n // using the example endpoint response for the 200 status code.\n // var mock = request.url.query.get(\"mock\")\n // if (mock) {\n // ctx.mock.set(true, mock)\n //}\n \n // For example, adding the header X-Mock: 200 will enable mocking,\n // using the example endpoint response for the 200 status code.\n var mock = request.header.get(\"X-Mock\");\n if (mock) {\n\t ctx.mock.set(true, mock);\n\t ctx.learn.set(false);\n }\n}", "functions": { "Audit_LogDataInResponse": { "description": "", @@ -25383,9 +25504,69 @@ "groups": { "docs": [ { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, + "items": [ + { + "_id": "parse-setting", + "type": "schemas" + }, + { + "_id": "POST_user-webhooks-parse-settings", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-parse-settings", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-parse-settings-hostname", + "type": "endpoints" + }, + { + "_id": "PATCH_user-webhooks-parse-settings-hostname-", + "type": "endpoints" + }, + { + "_id": "DELETE_user-webhooks-parse-settings-hostname", + "type": "endpoints" + } + ], + "name": "Settings - Inbound Parse" + }, + { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { - "_id": "POST_mail-send-beta", + "_id": "GET_alerts", + "type": "endpoints" + }, + { + "_id": "POST_alerts", + "type": "endpoints" + }, + { + "_id": "GET_alerts-alertid", + "type": "endpoints" + }, + { + "_id": "DELETE_alerts-alertid", + "type": "endpoints" + }, + { + "_id": "PATCH_alerts-alertid", + "type": "endpoints" + } + ], + "name": "Alerts" + }, + { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, + "items": [ + { + "_id": "POST_mail-send", "type": "endpoints" }, { @@ -25400,6 +25581,8 @@ "name": "Mail Send" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "GET_accesssettings-activity", @@ -25429,6 +25612,8 @@ "name": "IP Access Management" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "api_key_name_id", @@ -25466,6 +25651,8 @@ "name": "API Keys" }, { + "description": null, + "divider": false, "items": [ { "_id": "GET_scopes", @@ -25476,6 +25663,7 @@ }, { "description": null, + "divider": false, "items": [ { "_id": "GET_suppression-blocks", @@ -25497,6 +25685,8 @@ "name": "Blocks API" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "suppression_bounce", @@ -25522,6 +25712,8 @@ "name": "Bounces API" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "campaign_request", @@ -25579,6 +25771,8 @@ "name": "Campaigns API" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "mail_batch_id", @@ -25616,6 +25810,8 @@ "name": "Cancel Scheduled Sends" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "GET_categories", @@ -25625,6 +25821,8 @@ "name": "Categories" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "contactdb_custom_field_with_id", @@ -25662,6 +25860,8 @@ "name": "Contacts API - Custom Fields" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "contactdb_list", @@ -25711,6 +25911,8 @@ "name": "Contacts API - Lists" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "contactdb_recipient_count", @@ -25772,6 +25974,8 @@ "name": "Contacts API - Recipients" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "contactdb_segments", @@ -25813,6 +26017,8 @@ "name": "Contacts API - Segments" }, { + "description": null, + "divider": false, "items": [ { "_id": "credentials", @@ -25823,6 +26029,7 @@ }, { "description": null, + "divider": false, "items": [ { "_id": "GET_suppression-invalidemails", @@ -25844,6 +26051,8 @@ "name": "Invalid Emails API" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "POST_ips-pools-poolname-ips", @@ -25869,6 +26078,8 @@ "name": "IP Addresses" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "ip_pool", @@ -25898,6 +26109,8 @@ "name": "IP Pools" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "ip_warmup_response", @@ -25923,6 +26136,8 @@ "name": "IP Warmup" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "GET_user-settings-enforcedtls", @@ -25936,6 +26151,8 @@ "name": "Settings - Enforced TLS" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "mail_settings_address_whitelabel", @@ -26053,6 +26270,8 @@ "name": "Settings - Mail" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "partner_settings_new_relic", @@ -26074,6 +26293,8 @@ "name": "Settings - Partner" }, { + "description": null, + "divider": false, "items": [ { "_id": "subscription_tracking_settings", @@ -26124,6 +26345,7 @@ }, { "description": null, + "divider": false, "items": [ { "_id": "GET_suppression-spamreports", @@ -26145,6 +26367,8 @@ "name": "Spam Reports API" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "GET_stats", @@ -26154,6 +26378,8 @@ "name": "Stats - Global Stats" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "category_stats", @@ -26171,6 +26397,8 @@ "name": "Stats - Category Stats" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "stats", @@ -26200,6 +26428,8 @@ "name": "Stats - Subuser Stats" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "advanced_stats_mailbox_provider", @@ -26245,6 +26475,8 @@ "name": "Stats - Advanced Stats" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "GET_user-webhooks-parse-stats", @@ -26254,6 +26486,8 @@ "name": "Stats - Parse Webhook Stats" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "subuser", @@ -26311,6 +26545,8 @@ "name": "Subusers API" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "suppression_group_unsubscribes", @@ -26348,6 +26584,8 @@ "name": "Suppression Management - Unsubscribe Groups" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "POST_asm-groups-groupid-suppressions", @@ -26368,11 +26606,17 @@ { "_id": "GET_asm-suppressions-email", "type": "endpoints" + }, + { + "_id": "POST_asm-groups-groupid-suppressions-search", + "type": "endpoints" } ], "name": "Suppression Management - Suppressions" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "GET_suppression-unsubscribes", @@ -26394,6 +26638,8 @@ "name": "Suppression Management - Global Suppressions" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "transactional_template", @@ -26423,6 +26669,8 @@ "name": "Transactional Templates" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "transactional_template_version", @@ -26452,6 +26700,8 @@ "name": "Transactional Templates Versions" }, { + "description": null, + "divider": false, "items": [ { "_id": "user_scheduled_send_status", @@ -26502,6 +26752,7 @@ }, { "description": null, + "divider": false, "items": [ { "_id": "event_webhook_settings", @@ -26527,6 +26778,8 @@ "name": "Webhooks" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "whitelabel::domain", @@ -26588,6 +26841,8 @@ "name": "Whitelabel - Domains" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "ip_whitelabel", @@ -26617,6 +26872,8 @@ "name": "Whitelabel - IPs" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "link_whitelabel", @@ -26666,6 +26923,8 @@ "name": "Whitelabel - Links" }, { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, "items": [ { "_id": "global:ErrorResponse", @@ -26680,7 +26939,18 @@ "type": "schemas" } ], - "name": "Global" + "name": "Global: Models" + }, + { + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, + "items": [ + { + "_id": "authorizationHeader", + "type": "traits" + } + ], + "name": "Global: Traits" } ], "utilFuncs": [