Check out our spring line!
", + "id": 986724, + "ip_pool": "marketing", + "list_ids": [ + 110, + 124 + ], + "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" + }, + { + "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" } ] } + }, + "schema": { + "properties": { + "result": { + "_isOpen": true, + "items": { + "$ref": "#/definitions/campaign_response" + }, + "type": "array" + } + }, + "type": "object" } } }, - "summary": "**Update the name of an existing API Key**\n\nA JSON request body with a \"name\" property is required.\n\nThe API Keys featur", "security": [ { "Authorization": [] } - ] + ], + "summary": "Returns campaigns in reverse order they were created (newest first)\nReturns an empty array if no campaigns exist" }, - "get": { - "description": "Retrieve a single api key.\nIf the API Key ID does not exist an HTTP 404 will be returned.\n\n## URI Parameters\n\n| Param | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key for which you are requesting information.|", - "operationId": "Get an existing API Key", + "parameters": [], + "post": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\n\nNote: 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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Create a Campaign", "parameters": [ { - "name": "body", "in": "body", + "name": "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" - ] + "$ref": "#/definitions/campaign_request" } } ], + "produces": [ + "application/json" + ], "responses": { - "200": { + "201": { "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "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" - } - ] + "categories": [ + "spring line" + ], + "custom_unsubscribe_url": "", + "html_content": "Check out our spring line!
", + "id": 986724, + "ip_pool": "marketing", + "list_ids": [ + 110, + 124 + ], + "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" } + }, + "schema": { + "$ref": "#/definitions/campaign_response" } }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "400": { + "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"You've reached your limit of 250 campaigns. Please delete one or more and try again.\"", "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": "authorization required" + "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." } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, - "404": { - "description": "Unexpected error in API call. See HTTP response body for details.", + "401": { + "description": "", "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "unable to find API Key" - } - ] - } + "properties": {}, + "type": "object" } } }, - "summary": "Retrieve a single api key.\nIf the API Key ID does not exist an HTTP 404 will be returned.", "security": [ { "Authorization": [] } - ] - }, - "put": { - "description": "A JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.\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", - "operationId": "Update the name & scopes of an API Key", - "consumes": [ - "application/json" ], - "produces": [ + "summary": "{% info %}\nA campaign requires a title to be created.\nIn order to send or schedule the campaign, you will be required to" + } + }, + "/campaigns/{campaign_id}": { + "delete": { + "consumes": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "scopes": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - } - ], - "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.", + "description": "For more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Delete a Campaign", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "expected JSON request body with 'name' property" - } - ] - } + "type": "null" } }, "401": { "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "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" + "message": "authorization required" } ] } + }, + "schema": { + "properties": {}, + "type": "object" } + }, + "404": { + "description": "\"\": \"not found\"" } }, - "summary": "A JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "delete": { - "description": "**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", + "get": { "consumes": [ "application/json" ], + "description": "This is a place for notes and extra information about this endpoint. It is written\nin Markdown - more info in the [documentation](/docs/designer#markdown).\n\nThere are several special markdown helpers that automatically build tables\nand html off of your endpoint definition. You can find some examples in this content.\n\nClick the \"Open Editor\" button above to start editing this content.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Get a single campaign", + "parameters": [], "produces": [ "application/json" ], - "parameters": [], "responses": { - "204": { + "200": { "description": "", + "examples": { + "application/json": { + "categories": [ + "spring line" + ], + "custom_unsubscribe_url": "", + "html_content": "Check out our spring line!
", + "id": 986724, + "ip_pool": "marketing", + "list_ids": [ + 110, + 124 + ], + "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" + } + }, "schema": { - "type": "null" + "$ref": "#/definitions/campaign_response" } }, - "404": { + "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } }, + "schema": { + "properties": {}, + "type": "object" + } + }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "unable to find API Key" + "message": "not found" } ] } } } }, - "summary": "**Revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small", "security": [ { "Authorization": [] } - ] - } - }, - "/user/scheduled_sends/{batch_id}": { + ], + "summary": "" + }, "parameters": [ { - "name": "batch_id", "in": "path", + "name": "campaign_id", "required": true, - "type": "string" + "type": "integer" } ], "patch": { - "description": "Update the status 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": "Update user scheduled send information", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Update a Campaign", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "type": "object", "properties": { - "status": { - "type": "string", - "description": "The status you would like the scheduled send to have.", - "enum": [ - "cancel", - "pause" - ] + "categories": { + "description": "The categories you want to tag on this campaign.", + "items": { + "type": "string" + }, + "type": "array" + }, + "html_content": { + "description": "The HTML content of this campaign.", + "type": "string" + }, + "plain_content": { + "description": "The plain content of this campaign.", + "type": "string" + }, + "subject": { + "description": "The subject line for your campaign.", + "type": "string" + }, + "title": { + "description": "The title of the campaign.", + "type": "string" } }, "required": [ - "status" - ] + "title", + "subject", + "categories", + "html_content", + "plain_content" + ], + "title": "Update a Campaign request", + "type": "object" } } ], + "produces": [ + "application/json" + ], "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { + "200": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { - "errors": [ - { - "field": "status", - "message": "status must be either cancel or pause" - } - ] + "categories": [ + "summer line" + ], + "custom_unsubscribe_url": "", + "html_content": "Check out our summer line!
", + "id": 986724, + "ip_pool": "marketing", + "list_ids": [ + 110, + 124 + ], + "plain_content": "Check out our summer line!", + "segment_ids": [ + 110 + ], + "sender_id": 124451, + "status": "Draft", + "subject": "New Products for Summer!", + "suppression_group_id": 42, + "title": "May Newsletter" } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "schema": { + "$ref": "#/definitions/campaign_response" } }, - "404": { - "description": "\"\" : \"batch id not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "400": { + "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", "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": "batch id not found" + "message": "The JSON you have submitted cannot be parsed." } ] } } - } - }, - "summary": "Update the status of a scheduled send.", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "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 a cancellation or pause of a scheduled send", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } }, "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -5422,579 +3805,588 @@ } ] } - } - }, - "404": { - "description": "", + }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - }, + } + }, + "403": { + "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "batch id not found" + "message": "You may only update a campaign when it is in draft mode." } ] } - } - } - }, - "summary": "Delete the cancellation/pause of a scheduled send.", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Get 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": "Retrieve scheduled send", - "consumes": [ - "application/json" - ], - "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" - } - ] + "schema": { + "properties": {}, + "type": "object" } }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "authorization required" + "message": "not found" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations\na", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/user/scheduled_sends": { - "parameters": [], - "post": { - "description": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.\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": "Cancel or pause a scheduled send", + "/campaigns/{campaign_id}/schedules": { + "delete": { "consumes": [ "application/json" ], + "description": "A 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": "Unschedule a Scheduled Campaign", + "parameters": [], "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" - ] - } - } - ], "responses": { - "201": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/user_scheduled_send_status" + "type": "null" } }, - "400": { - "description": "\"\" : \"max limit reached\"\n\"batch_id\" : \"invalid batch id\"\n\"batch_id\" : \"a status for this batch id exists, try PATCH to update the status\"", - "schema": { - "type": "object", - "properties": {} - }, + "403": { + "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"This campaign is already Canceled.\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "max limit reached" + "message": "This campaign is already In Progress." }, { - "field": "batch_id", - "message": "invalid batch id" + "field": null, + "message": "This campaign is already Sent." }, { - "field": "batch_id", - "message": "a status for this batch id exists, try PATCH to update the status" + "field": null, + "message": "This campaign is already Paused." + }, + { + "field": null, + "message": "This campaign is already Canceled." } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "authorization required" + "message": "not found" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.", "security": [ { "Authorization": [] } - ] + ], + "summary": "A successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is" }, "get": { - "description": "Get 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 all scheduled sends", "consumes": [ "application/json" ], + "description": "View the time that this campaign is 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": "View Scheduled Time of a Campaign", + "parameters": [], "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" - } - ] + "send_at": 1490778528 } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/{subuser_name}": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "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 a subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", + }, "schema": { - "type": "object", - "properties": {} + "properties": { + "send_at": { + "format": "int64", + "type": "integer" + } + }, + "required": [ + "send_at" + ], + "title": "View Scheduled Time of a Campaign response", + "type": "object" } }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "authorization required" + "message": "not found" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, + "parameters": [ + { + "in": "path", + "name": "campaign_id", + "required": true, + "type": "integer" + } + ], "patch": { - "description": "This endpoint allows you to enable or disable a subuser.\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": "Enable/disable a subuser", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Changes the send_at time for the specified campaign.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Update a Scheduled Campaign", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "type": "object", "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." + "send_at": { + "format": "int64", + "type": "integer" } - } + }, + "required": [ + "send_at" + ], + "title": "Update a Scheduled Campaign request", + "type": "object" } } ], + "produces": [ + "application/json" + ], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "object", - "properties": {} + "properties": { + "id": { + "description": "The campaign ID", + "type": "integer" + }, + "send_at": { + "description": "The unix timestamp to send the campaign.", + "type": "integer" + }, + "status": { + "description": "The status of the schedule.", + "type": "string" + } + }, + "required": [ + "id", + "send_at", + "status" + ], + "title": "Update a Scheduled Campaign response", + "type": "object" } }, "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", "examples": { "application/json": { "errors": [ { - "message": "invalid username" + "field": "send_at", + "message": "Please choose a future time for sending your campaign." }, { - "message": "no fields provided" + "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" } ] } - } - }, - "401": { - "description": "", + }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - }, + } + }, + "403": { + "description": "\"send_at\": \"You cannot update the send_at value of non-scheduled campaign.\"", "examples": { "application/json": { "errors": [ { - "field": null, - "message": "authorization required" + "field": "send_at", + "message": "You cannot update the send_at value of non-scheduled campaign." } ] } - } - }, - "500": { - "description": "", + }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - }, + } + }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ { - "message": "unable to enable user" + "field": null, + "message": "not found" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/ips/assigned": { - "parameters": [], - "get": { - "description": "Retrieve a list of your IP addresses.", - "operationId": "List all assigned IPs", - "consumes": [ - "application/json" ], - "produces": [ + "summary": "Changes the send_at time for the specified campaign." + }, + "post": { + "consumes": [ "application/json" ], - "parameters": [], - "responses": { - "200": { - "description": "", + "description": "Send your campaign at a specific date and time.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Schedule a Campaign", + "parameters": [ + { + "in": "body", + "name": "body", "schema": { - "type": "array", - "title": "List all assigned IPs response", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": "integer" - } - } - } - }, - "examples": { - "application/json": [ - { - "ip": "167.89.21.3", - "pools": [ - "new_test5" - ], - "warmup": true, - "start_date": 1409616000 + "properties": { + "send_at": { + "description": "The unix timestamp for the date and time you would like your campaign to be sent out.", + "type": "integer" } - ] + }, + "required": [ + "send_at" + ], + "title": "Schedule a Campaign request", + "type": "object" } } - }, - "summary": "See only assigned IPs.", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/plain_content": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get plain content mail settings", - "consumes": [ - "application/json" ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "200": { + "201": { "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - }, "examples": { "application/json": { - "enabled": false + "id": 1234, + "send_at": 1489771528, + "status": "Scheduled" } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update plain content mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", + }, "schema": { - "type": "object", "properties": { - "enabled": { - "type": "boolean" + "id": { + "description": "The campaign ID.", + "type": "integer" + }, + "send_at": { + "description": "The date time you scheduled your campaign to be sent.", + "type": "integer" + }, + "status": { + "description": "The status of your campaign.", + "enum": [ + "Scheduled" + ], + "type": "string" } + }, + "required": [ + "id", + "send_at", + "status" + ], + "title": "Schedule a Campaign response", + "type": "object" + } + }, + "400": { + "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", + "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" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "200": { + }, + "401": { "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "403": { + "description": "\"\": \"You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.\"", + "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." + } + ] } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { - "enabled": false + "errors": [ + { + "field": null, + "message": "not found" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/campaigns/{campaign_id}/schedules": { + "/campaigns/{campaign_id}/schedules/now": { "parameters": [ { - "name": "campaign_id", "in": "path", + "name": "campaign_id", "required": true, "type": "integer" } ], - "get": { - "description": "View the time that this campaign is 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": "View Scheduled Time of a Campaign", + "post": { "consumes": [ "application/json" ], + "description": "Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Send a Campaign", + "parameters": [], "produces": [ "application/json" ], - "parameters": [], "responses": { - "200": { + "201": { "description": "", + "examples": { + "application/json": { + "id": 1234, + "status": "Scheduled" + } + }, "schema": { - "title": "View Scheduled Time of a Campaign response", - "type": "object", "properties": { - "send_at": { - "type": "integer", - "format": "int64" + "id": { + "format": "int64", + "type": "integer" + }, + "status": { + "type": "string" } }, "required": [ - "send_at" - ] - }, + "id", + "status" + ], + "title": "Send a Campaign response", + "type": "object" + } + }, + "400": { + "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", "examples": { "application/json": { - "send_at": 1490778528 + "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" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, - "404": { - "description": "\"\": \"not found\"", + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, "schema": { "$ref": "#/definitions/global:ErrorResponse" + } + }, + "403": { + "description": "\"\": \"You may only send a campaign when it is in draft mode.\"", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "You may only send a campaign when it is in draft mode." + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ @@ -6004,76 +4396,75 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - }, - "patch": { - "description": "Changes the send_at time for the specified campaign.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Update a Scheduled Campaign", - "consumes": [ - "application/json" ], - "produces": [ + "summary": "" + } + }, + "/campaigns/{campaign_id}/schedules/test": { + "parameters": [ + { + "in": "path", + "name": "campaign_id", + "required": true, + "type": "integer" + } + ], + "post": { + "consumes": [ "application/json" ], + "description": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Send a Test Campaign", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "title": "Update a Scheduled Campaign request", - "type": "object", "properties": { - "send_at": { - "type": "integer", - "format": "int64" + "to": { + "description": "The email address that should receive the test campaign.", + "format": "email", + "type": "string" } }, "required": [ - "send_at" - ] + "to" + ], + "type": "object" } } ], + "produces": [ + "application/json" + ], "responses": { - "200": { + "204": { "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." + "to": { + "type": "string" } }, "required": [ - "id", - "send_at", - "status" - ] + "to" + ], + "title": "Send a Test Campaign request", + "type": "object" } }, "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"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" - }, + "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"sender_id\": \"Please assign a sender identity to your campaign before sending a test.\"", "examples": { "application/json": { "errors": [ @@ -6085,35 +4476,19 @@ "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." + { + "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" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, "404": { "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -6123,340 +4498,716 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "Changes the send_at time for the specified campaign.", "security": [ { "Authorization": [] } - ] - }, - "delete": { - "description": "A 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": "Unschedule a Scheduled Campaign", + ], + "summary": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]" + } + }, + "/categories": { + "get": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Get categories", + "parameters": [ + { + "in": "query", + "name": "limit", + "type": "integer" + }, + { + "in": "query", + "name": "sort_by", + "type": "string" + }, + { + "in": "query", + "name": "order", + "type": "string" + }, + { + "in": "query", + "name": "category", + "type": "string" + }, + { + "in": "query", + "name": "offset", + "type": "integer" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "204": { + "200": { "description": "", - "schema": { - "type": "null" - } - }, - "403": { - "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"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." + "application/json": [ + { + "category": "category 1" + }, + { + "category": "category 2" + } + ] + }, + "schema": { + "items": { + "properties": { + "category": { + "type": "string" } - ] - } + }, + "type": "object" + }, + "type": "array" } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/categories/stats": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve Email Statistics for Categories", + "parameters": [ + { + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + { + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", + "in": "query", + "name": "categories", + "required": true, + "type": "string" + }, + { + "description": "The number of results to include.", + "in": "query", + "maximum": 500, + "name": "limit", + "required": false, + "type": "integer" + }, + { + "description": "The number of results to skip.", + "in": "query", + "name": "offset", + "required": false, + "type": "integer" + }, + { + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ + { + "date": "2015-10-01", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "docs", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "mattscategory", + "type": "category" + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "docs", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "mattscategory", + "type": "category" + } + ] + } + ] }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } + "schema": { + "items": { + "$ref": "#/definitions/category_stats" + }, + "type": "array" } } }, - "summary": "A successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "post": { - "description": "Send your campaign at a specific date and time.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Schedule a Campaign", + "parameters": [] + }, + "/categories/stats/sums": { + "get": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "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": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", "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" - ] - } + "description": "The metric that you want to sort by. Must be a single metric.", + "in": "query", + "name": "sort_by_metric", + "required": false, + "type": "string" + }, + { + "description": "The direction you want to sort.", + "enum": [ + "desc", + "asc" + ], + "in": "query", + "name": "sort_by_direction", + "required": false, + "type": "string" + }, + { + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" + }, + { + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "Limits the number of results returned.", + "in": "query", + "name": "limit", + "required": false, + "type": "integer" + }, + { + "description": "The point in the list to begin retrieving results.", + "in": "query", + "name": "offset", + "required": false, + "type": "integer" + }, + { + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" } ], + "produces": [ + "application/json" + ], "responses": { - "201": { + "200": { "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\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"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" - }, + "date": "2015-01-01", + "stats": [ { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" + "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" }, { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." + "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" }, { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "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" }, { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "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" }, { - "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" + "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" } ] } + }, + "schema": { + "properties": { + "": { + "$ref": "#/definitions/category_stats" + } + }, + "type": "object" } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/clients/stats": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve email statistics by client type.", + "parameters": [ + { + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" }, - "401": { + { + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "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" + "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" + } + ] + } + ] }, - "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" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } + "items": { + "$ref": "#/definitions/advanced_stats_opens" + }, + "type": "array" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } + ], + "summary": "Gets email statistics by client type." + }, + "parameters": [] }, - "/suppression/bounces/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "type": "string" - } - ], + "/clients/{client_type}/stats": { "get": { - "description": "", - "operationId": "Get a Bounce", "consumes": [ "application/json" ], + "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": "Retrieve stats by a specific client type.", + "parameters": [ + { + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" + }, + { + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "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" + "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" + } + ] } ] + }, + "schema": { + "items": { + "$ref": "#/definitions/advanced_stats_opens" + }, + "type": "array" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "Gets email statistics by a single client type." }, - "delete": { - "description": "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. \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 a bounce", + "parameters": [ + { + "description": "Specifies the type of client to retrieve stats for. Must be either \"phone\", \"tablet\", \"webmail\", or \"desktop\".", + "enum": [ + "phone", + "tablet", + "webmail", + "desktop" + ], + "in": "path", + "name": "client_type", + "required": true, + "type": "string" + } + ] + }, + "/contactdb/custom_fields": { + "get": { "consumes": [ "application/json" ], + "description": "Get 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": "List All Custom Fields", + "parameters": [], "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" - } - ], "responses": { - "204": { + "200": { "description": "", + "examples": { + "application/json": { + "lists": [ + { + "id": 1, + "name": "the jones", + "recipient_count": 1 + } + ] + } + }, "schema": { - "type": "object", - "properties": {} + "properties": { + "custom_fields": { + "items": { + "$ref": "#/definitions/contactdb_custom_field_with_id" + }, + "type": "array" + } + }, + "required": [ + "custom_fields" + ], + "title": "List All Custom Fields response", + "type": "object" } }, "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -6466,1404 +5217,1441 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/mail_settings/template": { + ], + "summary": "" + }, "parameters": [], - "get": { - "description": "", - "operationId": "Get template mail settings", + "post": { "consumes": [ "application/json" ], + "description": "Create a custom field.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Create a Custom Field", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "name": { + "type": "string" + }, + "type": { + "type": "string" + } + }, + "type": "object" + } + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "200": { + "201": { "description": "", + "examples": { + "application/json": { + "id": 1, + "name": "pet", + "type": "text" + } + }, "schema": { - "type": "object", "properties": { - "enabled": { - "type": "boolean" + "id": { + "type": "integer" }, - "html_content": { + "name": { + "type": "string" + }, + "type": { "type": "string" } - } - }, + }, + "type": "object" + } + }, + "400": { + "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", "examples": { "application/json": { - "enabled": false, - "html_content": "<% body %>Example
\n" + "errors": [ + { + "field": null, + "message": "Returned if request body is invalid JSON" + }, + { + "field": "type", + "message": "Returned if custom field type is invalid or not provided" + }, + { + "field": "name", + "message": "Returned if custom field name is not provided" + } + ] } } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - }, - "patch": { - "description": "", - "operationId": "Update template mail settings", + ], + "summary": "" + } + }, + "/contactdb/custom_fields/{custom_field_id}": { + "delete": { "consumes": [ "application/json" ], + "description": "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 a Custom Field", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", + "responses": { + "202": { + "description": "", + "examples": { + "application/json": { + "message": "Custom Field delete is processing." + } + }, "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "400": { + "description": "\"id\" : \"Returned if custom_field_id is not valid\"", + "examples": { + "application/json": { + "errors": [ + { + "message": "Custom field in use by one or more segment conditions" + }, + { + "message": "Custom field ID does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "200": { + }, + "401": { "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", "examples": { "application/json": { - "enabled": false, - "html_content": "<% body %>Example
\n" + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/mail_settings/address_whitelist": { - "parameters": [], + ], + "summary": "" + }, "get": { - "description": "", - "operationId": "Get address whitelist mail settings", "consumes": [ "application/json" ], + "description": "Get 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 a Custom Field", + "parameters": [ + { + "description": "The ID of the custom field you would like to retrieve", + "in": "query", + "name": "custom_field_id", + "required": true, + "type": "number" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", + "examples": { + "application/json": { + "id": 1, + "name": "pet", + "type": "text" + } + }, + "schema": { + "$ref": "#/definitions/contactdb_custom_field_with_id" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + }, "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", "examples": { "application/json": { - "enabled": false, - "list": [ - "example.com" + "errors": [ + { + "message": "Custom field ID does not exist" + } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "patch": { - "description": "", - "operationId": "Update address whitelist mail settings", + "parameters": [ + { + "in": "path", + "name": "custom_field_id", + "required": true, + "type": "string" + } + ] + }, + "/contactdb/lists": { + "delete": { "consumes": [ "application/json" ], + "description": "Delete multiple lists.\n\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 Multiple lists", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", + "responses": { + "204": { + "description": "", "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "list": { - "type": "array", - "items": { - "type": "string" + "type": "null" + } + }, + "400": { + "description": "\"id\" : \"Returned if all list ids are not valid\"", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "list id was invalid" } - } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "200": { + }, + "401": { "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" - }, "examples": { "application/json": { - "enabled": true, - "list": [ - "email1@example.com" + "errors": [ + { + "field": null, + "message": "authorization required" + } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/mail_settings/footer": { - "parameters": [], + ], + "summary": "" + }, "get": { - "description": "", - "operationId": "Get footer mail settings [params can be null?]", "consumes": [ "application/json" ], + "description": "Returns an empty list if you GET and no lists exist on your account.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List All Lists", + "parameters": [], "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" + "lists": [ + { + "id": 1, + "name": "the jones", + "recipient_count": 1 + } + ] } + }, + "schema": { + "properties": { + "lists": { + "items": { + "$ref": "#/definitions/contactdb_list" + }, + "type": "array" + } + }, + "required": [ + "lists" + ], + "title": "List All Lists response", + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "Returns an empty list if you GET and no lists exist on your account." }, - "patch": { - "description": "", - "operationId": "Update footer mail settings", + "parameters": [], + "post": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Create a list for your 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": "Create a List", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "$ref": "#/definitions/mail_settings_footer" + "properties": { + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "title": "Create a List request", + "type": "object" } } ], + "produces": [ + "application/json" + ], "responses": { - "200": { + "201": { "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_footer" - }, "examples": { "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" + "id": 1, + "name": "your list name", + "recipient_count": 0 } + }, + "schema": { + "$ref": "#/definitions/contactdb_list" } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/suppressions/global/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "", - "operationId": "Retrieve a Global Suppression", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", + }, + "400": { + "description": "\"name\" : \"Returned if list name is a duplicate of an existing list or segment\"\n\"name\" : \"Returned if list name is not a string\"\n\"\" : \"Returned if request body is invalid JSON\"", + "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" + } + ] + } + }, "schema": { - "title": "Retrieve a Global Suppression response", - "type": "object", - "properties": { - "recipient_email": { - "type": "string" - } - }, - "required": [ - "recipient_email" - ] + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "", - "operationId": "Delete a Global Suppression", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "" - } - }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/tracking_settings/google_analytics": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get Google Analytics Settings", + "/contactdb/lists/{list_id}": { + "delete": { "consumes": [ "application/json" ], + "description": "Delete a list 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 a List", + "parameters": [ + { + "description": "Adds the ability to delete all contacts on the list in addition to deleting the list.", + "enum": [ + true, + false + ], + "in": "query", + "name": "delete_contacts", + "type": "boolean" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "200": { + "202": { "description": "", "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not valid\"", + "examples": { + "application/json": { + "errors": [ + { + "field": "delete_contacts", + "message": "delete_contacts not a bool" + }, + { + "field": "list_id", + "message": "Returned if list_id is not valid" + } + ] } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", "examples": { "application/json": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "examples": { + "application/json": { + "errors": [ + { + "message": "List not found: 5" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "patch": { - "description": "", - "operationId": "Update Google Analytics Settings", + "get": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Get a single list. \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 a single list.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_source": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_term": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_campaign": { - "type": "string" - } - } - } + "description": "The ID of the list to retrieve.", + "in": "query", + "name": "list_id", + "type": "number" } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } + "examples": { + "application/json": { + "id": 1, + "name": "listname", + "recipient_count": 0 } }, + "schema": { + "$ref": "#/definitions/contactdb_list" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not valid\"", "examples": { "application/json": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" + "errors": [ + { + "message": "invalid id" + } + ] } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/partner_settings/new_relic": { - "parameters": [], - "patch": { - "description": "**This endpoint allows you to update or change your 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": "Updates New Relic partner settings.", - "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." - } - } + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "200": { + }, + "401": { "description": "", - "schema": { - "$ref": "#/definitions/partner_settings_new_relic" + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", "examples": { "application/json": { - "enable_subuser_statistics": true, - "enabled": true, - "license_key": "" + "errors": [ + { + "field": null, + "message": "List ID does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "get": { - "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": "Returns all New Relic partner settings.", + "parameters": [ + { + "in": "path", + "name": "list_id", + "required": true, + "type": "string" + } + ], + "patch": { "consumes": [ "application/json" ], + "description": "Update the name of a list.\n\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Update a List", + "parameters": [ + { + "description": "The ID of the list you are updating.", + "in": "query", + "name": "list_id", + "required": true, + "type": "number" + }, + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "name": { + "description": "The new name for your list. ", + "type": "string" + } + }, + "required": [ + "name" + ], + "title": "Update a List request", + "type": "object" + } + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/partner_settings_new_relic" + "properties": {}, + "type": "object" + } + }, + "400": { + "description": "\"name\" : \"Returned if list name is a duplicate of existing list or segment\"\n\"name\" : \"Returned if list name is invalid or not provided\"\n\"list_id\" : \"Returned if list_id is not valid\"\n\"\" : \"Returned if request body is invalid JSON\"", + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", "examples": { "application/json": { - "enable_subuser_statistics": false, - "enabled": true, - "license_key": "" + "errors": [ + { + "message": "List ID does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/partner_settings": { - "parameters": [], + "/contactdb/lists/{list_id}/recipients": { "get": { - "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": "Returns a list of all partner settings.", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "List all the recipients currently on a specific list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List Recipients on a List", "parameters": [ { - "name": "limit", + "description": "Page index of first recipient to return (must be a positive integer)", "in": "query", - "description": "The number of settings to return per page.", + "name": "page", + "required": false, "type": "integer" }, { - "name": "offset", + "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", "in": "query", - "description": "The paging offset.", + "name": "page_size", + "required": false, "type": "integer" + }, + { + "description": "The ID of the list whose recipients you are requesting.", + "in": "query", + "name": "list_id", + "required": true, + "type": "number" } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the partner." + "examples": { + "application/json": { + "recipients": [ + { + "created_at": 1433348344, + "custom_fields": [ + { + "id": 6234, + "name": "age", + "type": "number", + "value": null }, - "enabled": { - "type": "boolean", - "description": "Indicates if this partner setting has been enabled." + { + "id": 6233, + "name": "country", + "type": "text", + "value": null }, - "name": { - "type": "string", - "description": "The name of the partner setting." + { + "id": 6235, + "name": "fname", + "type": "text", + "value": "Example" }, - "description": { - "type": "string", - "description": "A description of this partner setting." + { + "id": 6239, + "name": "lname", + "type": "text", + "value": "User" + }, + { + "id": 6240, + "name": "lname", + "type": "text", + "value": null } - }, - "required": [ - "title", - "enabled", - "name", - "description" - ] + ], + "email": "example@example.com", + "first_name": "Example", + "id": "ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==", + "last_clicked": 1438616117, + "last_emailed": 1438613272, + "last_name": "User", + "last_opened": 1438616109, + "updated_at": 1438616119 } - } + ] } }, + "schema": { + "properties": { + "recipients": { + "items": { + "$ref": "#/definitions/contactdb_recipient" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"", "examples": { "application/json": { - "result": [ + "errors": [ { - "title": "Partner title", - "enabled": true, - "name": "partner_name", - "description": "A description of a partner." + "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" } ] } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/spam_check": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update spam check mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", + }, "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "url": { - "type": "string" - }, - "max_score": { - "type": "integer" - } - } + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_spam_check" - }, + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", "examples": { "application/json": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" + } + ] } + }, + "schema": { + "properties": {}, + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "get": { - "description": "", - "operationId": "Get spam check mail settings", + "parameters": [ + { + "in": "path", + "name": "list_id", + "required": true, + "type": "string" + } + ], + "post": { "consumes": [ "application/json" ], + "description": "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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Add Multiple Recipients to a List", + "parameters": [ + { + "description": "The list to add your recipients to. ", + "in": "query", + "name": "list_id", + "required": true, + "type": "number" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "200": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_spam_check" - }, + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"\" : \"Returned if no valid recipient ids were passed\"\n\"\" : \"Returned if no recipients were added\"\n\"\" : \"Returned if request body is invalid JSON\"", "examples": { "application/json": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" + "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" + } + ] } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/forward_spam": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update forward spam mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", + }, "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "200": { + }, + "401": { "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" - }, "examples": { "application/json": { - "email": "", - "enabled": false + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get forward spam mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"list_id\": \"Returned if list_id does not exist\"", "examples": { "application/json": { - "email": "", - "enabled": true + "errors": [ + { + "field": "list_id", + "message": "list_id does not exist" + }, + { + "field": "recipient_id", + "message": "recipient_id does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they " } }, - "/mail_settings/forward_bounce": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update forward bounce mail settings", + "/contactdb/lists/{list_id}/recipients/{recipient_id}": { + "delete": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Delete a single recipient from a list.\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 a Single Recipient from a Single List", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "email": { - "type": "string" - } - } - } + "description": "The ID of the list you are taking this recipient away from.", + "in": "query", + "name": "list_id", + "required": true, + "type": "number" + }, + { + "description": "The ID of the recipient to take off the list.", + "in": "query", + "name": "recipient_id", + "required": true, + "type": "number" } ], + "produces": [ + "application/json" + ], "responses": { - "200": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce" - }, + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"recipient_id\" : \"Returned if recipient_id is not valid\"", "examples": { "application/json": { - "email": "", - "enabled": true + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" + }, + { + "field": "recipient_id", + "message": "no valid recipients were provided" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get forward bounce mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { + }, + "401": { "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce" + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", "examples": { "application/json": { - "enabled": false, - "email": null + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id does not exist" + }, + { + "field": "recipient_id", + "message": "Returned if recipient_id does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/categories": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get categories", - "consumes": [ - "application/json" ], - "produces": [ + "summary": "" + }, + "parameters": [ + { + "in": "path", + "name": "list_id", + "required": true, + "type": "string" + }, + { + "in": "path", + "name": "recipient_id", + "required": true, + "type": "string" + } + ], + "post": { + "consumes": [ "application/json" ], + "description": "Add a recipient to a list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Add a Single Recipient to a List", "parameters": [ { - "name": "limit", - "in": "query", - "type": "integer" - }, - { - "name": "sort_by", - "in": "query", - "type": "string" - }, - { - "name": "order", + "description": "The ID of the list to add the recipient to.", "in": "query", - "type": "string" + "name": "list_id", + "type": "number" }, { - "name": "category", + "description": "The recipient you are adding to the list indicated.", "in": "query", + "name": "recipient_id", "type": "string" - }, - { - "name": "offset", - "in": "query", - "type": "integer" } ], + "produces": [ + "application/json" + ], "responses": { - "200": { + "201": { "description": "", "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "category": { - "type": "string" + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is invalid\"\n\"recipient_id\" : \"Returned if recipient_id is invalid\"", + "examples": { + "application/json": { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" + }, + { + "field": "recipient_id", + "message": "Returned if recipient_id is invalid" } - } + ] } }, - "examples": { - "application/json": [ - { - "category": "category 1" - }, - { - "category": "category 2" - } - ] + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/account": { - "parameters": [], - "get": { - "description": "Your user's account information includes the user's account type and reputation.", - "operationId": "Get a user's account information.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { + }, + "401": { "description": "", - "schema": { - "title": "GET User Account response", - "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": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", "examples": { "application/json": { - "reputation": 100, - "type": "paid" + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id does not exist" + }, + { + "field": "recipient_id", + "message": "Returned if recipient_id does not exist" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/mail_settings": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get all mail settings", + "/contactdb/recipients": { + "delete": { "consumes": [ "application/json" ], + "description": "Deletes one or more recipients. The body is a list of recipient ids to delete.\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 Recipient", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "limit", - "in": "query", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "type": "integer" - } - ], "responses": { "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string" - }, - "enabled": { - "type": "boolean" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - } - } - } - } - } - }, + "description": "" + }, + "400": { + "description": "\"\" : \"Returned if no recipients are deleted\"\n\"\" : \"Returned if all of the provided recipient ids are invalid\"\n\"\" : \"Returned if request body is not valid json\"", "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." - }, + "errors": [ { - "title": "Plain Content", - "enabled": false, - "name": "plain_content", - "description": "Convert your plain text emails to HTML." - }, + "message": "No recipient ids provided" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ { - "title": "Spam Checker", - "enabled": true, - "name": "spam_check", - "description": "Check outbound messages for spam content." + "field": null, + "message": "authorization required" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/whitelabel/ips": { - "parameters": [], + ], + "summary": "Deletes one or more recipients. The body is a list of recipient ids to delete." + }, "get": { - "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": "Retrieve all IP whitelabels", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Batch 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 contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List Recipients [waiting on Bryan Adamson's response]", "parameters": [ { - "name": "limit", + "description": "Page index of first recipients to return (must be a positive integer)", "in": "query", - "description": "The number of results to retrieve.", + "name": "page", "type": "integer" }, { - "name": "offset", + "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", "in": "query", - "description": "The point in the list of results to begin retrieving IPs from.", + "name": "page_size", "type": "integer" - }, - { - "name": "ip", - "in": "query", - "description": "The IP segment that you would like to use in a prefix search.", - "type": "string" } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/ip_whitelabel" - } - }, + "properties": { + "recipients": { + "items": { + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "recipients" + ], + "title": "List Recipients response", + "type": "object" + } + }, + "400": { + "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"" + }, + "401": { + "description": "", "examples": { - "application/json": [ - { - "id": 1, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example.com", - "user_id": 8 - } - ], - "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" - } - }, - { - "id": 2, - "ip": "192.168.1.2", - "rdns": "o2.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example2.com", - "user_id": 9 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o2.email.example.com", - "data": "192.168.1.2" + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" } - } - ] + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "{% info %}\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\n" }, - "post": { - "description": "**This endpoint allows you to create an IP whitelabel.**\n\nWhen creating an IP whitelable, you should use the same subdomain that you used when you created a domain 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": "Create an IP whitelabel", + "parameters": [], + "patch": { "consumes": [ "application/json" ], + "description": "Updates one or more recipients. The body is an array of recipient objects.\n\nIt 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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Update Recipient", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address that you want to whitelabel." - }, - "subdomain": { - "type": "string", - "description": "The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The root, or sending, domain that will be used to send message from the IP." - } - }, - "required": [ - "ip", - "subdomain", - "domain" - ] - } - } - ], "responses": { "201": { "description": "", "schema": { - "$ref": "#/definitions/ip_whitelabel" + "$ref": "#/definitions/contactdb_recipient_response" + } + }, + "400": { + "description": "\"\" : \"Returned if request body is not valid json\"", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "Request body is not valid json" + } + ] + } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", "examples": { "application/json": { - "id": 123, - "ip": "192.168.1.2", - "rdns": "o1.email.example.com", - "users": [], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.2" - } + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/contactdb/segments/{segment_id}/recipients": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "get": { - "description": "List all of the recipients in a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients On a Segment", + ], + "summary": "Updates one or more recipients. The body is a list of recipient objects." + }, + "post": { "consumes": [ "application/json" ], + "description": "Add a recipient to your contactdb. 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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Add recipients", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "page", - "in": "query", - "type": "integer" - }, - { - "name": "page_size", - "in": "query", - "type": "integer" - } - ], "responses": { - "200": { + "201": { "description": "", - "schema": { - "title": "List Recipients On a Segment response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" + "examples": { + "application/json": { + "error_count": 1, + "error_indices": [ + 2 + ], + "errors": [ + { + "error_indices": [ + 2 + ], + "message": "Invalid email." } - } - }, - "required": [ - "recipients" - ] + ], + "new_count": 2, + "persisted_recipients": [ + "YUBh", + "bWlsbGVyQG1pbGxlci50ZXN0" + ], + "updated_count": 0 + } }, + "schema": { + "$ref": "#/definitions/contactdb_recipient_response" + } + }, + "400": { + "description": "\"\" : \"Returned if request body is not valid json\"", "examples": { "application/json": { - "recipients": [ + "errors": [ { - "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" - } - ] + "field": null, + "message": "Request body is not valid json" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"" - }, "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -7873,65 +6661,45 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"" } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/suppression/bounces": { - "parameters": [], - "delete": { - "description": "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete 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)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes.", - "operationId": "Delete bounces", + "/contactdb/recipients/billable_count": { + "get": { "consumes": [ "application/json" ], + "description": "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.\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 the count of billable recipients", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter." - }, - "emails": { - "type": "array", - "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", - "items": { - "type": "string" - } - } - } - } - } - ], "responses": { - "204": { + "200": { "description": "", + "examples": { + "application/json": { + "recipient_count": 1234 + } + }, "schema": { - "type": "null" + "$ref": "#/definitions/contactdb_recipient_count" } }, "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -7941,90 +6709,46 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, + "parameters": [] + }, + "/contactdb/recipients/count": { "get": { - "description": "Bounces 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": "List all bounces", "consumes": [ "application/json" ], + "description": "Get a count of the current number of recipients in your contact database.\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 a Count of Recipients", + "parameters": [], "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" - }, - { - "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" - } - ], "responses": { "200": { "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "number" - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string" - }, - "status": { - "type": "string" - } - } + "examples": { + "application/json": { + "recipient_count": 1234 } }, - "examples": { - "application/json": [ - { - "created": 1250337600, - "email": "example@example.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" - }, - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1Check out our spring line!
", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - }, "examples": { "application/json": { - "errors": [ + "segments": [ { - "field": null, - "message": "authorization required" + "conditions": [ + { + "field": "age", + "operator": "lt", + "value": "25" + } + ], + "id": 1234, + "name": "Age segments < 25", + "recipient_count": 8 + }, + { + "conditions": [ + { + "field": "email", + "operator": "contains", + "value": "@gmail.com" + } + ], + "id": 2345, + "name": "email address - gmail", + "recipient_count": 0 } ] } + }, + "schema": { + "properties": { + "segments": { + "items": { + "$ref": "#/definitions/contactdb_segments" + }, + "type": "array" + } + }, + "required": [ + "segments" + ], + "title": "List All Segments response", + "type": "object" } }, - "404": { - "description": "\"\": \"not found\"", + "401": { + "description": "", "examples": { "application/json": { "errors": [ { "field": null, - "message": "not found" + "message": "authorization required" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "patch": { - "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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Update a Campaign", + "parameters": [], + "post": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment 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. \n\nSegments 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\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Create a Segment", "parameters": [ { - "name": "body", "in": "body", + "name": "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": { - "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" - ] + "$ref": "#/definitions/contactdb_segments" } } ], + "produces": [ + "application/json" + ], "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" + "conditions": [ + { + "and_or": "", + "field": "last_name", + "operator": "eq", + "value": "Miller" + }, + { + "and_or": "and", + "field": "last_clicked", + "operator": "gt", + "value": "01/02/2015" + }, + { + "and_or": "or", + "field": "clicks.campaign_identifier", + "operator": "eq", + "value": "513" + } ], - "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" + "id": 1, + "list_id": 4, + "name": "Last Name Miller", + "recipient_count": 0 } + }, + "schema": { + "$ref": "#/definitions/contactdb_segments_with_id" } }, "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", + "description": "\"name\" : \"Returned if the name is not valid\"\n\"list_id\" : \"Returned if the list_id is not valid\"\n\"and_or\" : \"Returned if and_or and set value is not passed into the request body\"\n\"and_or\" : \"Returned if and_or is set on the only condition passed\"\n\"and_or\" : \"Returned if and_or is set on all conditions\"\n\"and_or\" : \"Returned if and_or is not set on more than one condition and less than all conditions\"\n\"operator\" : \"Returned if operator and set value is not passed into the request body\"\n\"value\" : \"Returned if value and set value is not passed into the request body\"\n\"field\" : \"Returned if field and set value is not passed into the request body\"\n\"\" : \"Returned if request body is not valid json\"\n\"\" : \"Returned if invalid value is passed into one of the request body parameters\"", "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" + "message": "request body is not valid json" }, { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" + "message": "invalid value is passed into one of the request body parameters" }, { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" + "field": "field", + "message": "field and set value is not passed into the request body" }, { - "field": "sender_id", - "message": "sender_id does not exist" + "field": "value", + "message": "value and set value is not passed into the request body" }, { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" + "field": "operator", + "message": "operator and set value is not passed into the request body" }, { - "field": "list_ids", - "message": "list_ids do not all exist" + "field": "and_or", + "message": "and_or is not set on more than one condition and less than all conditions" }, { - "field": "segment_ids", - "message": "segment_ids do not all exist" + "field": "and_or", + "message": "and_or is set on all conditions" }, { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" + "field": "and_or", + "message": "and_or is set on the only condition passed" }, { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" + "field": "and_or", + "message": "and_or and set value is not passed into the request body" }, { - "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": "list_id", + "message": "the list_id is not valid" }, { - "field": null, - "message": "The JSON you have submitted cannot be parsed." + "field": "name", + "message": "the name is not valid" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -8650,303 +7432,334 @@ } ] } - } - }, - "403": { - "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", - "schema": { - "type": "object", - "properties": {} }, - "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" - } - ] - } } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/asm/suppressions/global": { - "parameters": [], - "post": { - "description": "Global Suppressions are email addresses that will not receive any emails.", - "operationId": "Add recipient addresses to the global suppression group.", + "/contactdb/segments/{segment_id}": { + "delete": { "consumes": [ "application/json" ], + "description": "Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment.\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 a Segment", + "parameters": [ + { + "description": "True to delete all contacts matching the segment in addition to deleting the segment", + "in": "query", + "name": "delete_contacts", + "type": "boolean" + } + ], "produces": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", + "responses": { + "204": { + "description": "", "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" + "type": "null" + } + }, + "400": { + "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not a valid boolean\"", + "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" } - } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - ], - "responses": { - "201": { + }, + "401": { "description": "", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" } - } + ] } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", "examples": { "application/json": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" + "errors": [ + { + "field": "segment_id", + "message": "segment_id does not exist" + } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/tracking_settings/subscription": { - "parameters": [], + ], + "summary": "" + }, "get": { - "description": "", - "operationId": "Get Subscription Tracking Settings", "consumes": [ "application/json" ], + "description": "Get a single segment 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": "Retrieve a Segment", + "parameters": [ + { + "description": "The ID of the segment you want to request.", + "in": "query", + "name": "segment_id", + "required": true, + "type": "number" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "url": { - "type": "string" - } - } - }, "examples": { "application/json": { - "enabled": true, - "html_content": "Something something unsubscribe <% %> something something
\n", - "landing": "subscribehere
\n", - "plain_content": "Something something unsubscribe <% %> something something", - "replace": "thetag", - "url": "" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update Subscription Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "landing": { - "type": "string" - }, - "url": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } + "conditions": [ + { + "and_or": "", + "field": "last_name", + "operator": "eq", + "value": "Miller" + } + ], + "id": 1, + "list_id": 4, + "name": "Last Name Miller", + "recipient_count": 1 } + }, + "schema": { + "$ref": "#/definitions/contactdb_segments" } - } - ], - "responses": { - "200": { - "description": "", + }, + "400": { + "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", + "examples": { + "application/json": { + "errors": [ + { + "message": "if segment_id is not valid" + } + ] + } + }, "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "landing": { - "type": "string" - }, - "url": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", "examples": { "application/json": { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" + "errors": [ + { + "message": "segment_id not found" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/mail/batch/{batch_id}": { + ], + "summary": "" + }, "parameters": [ { - "name": "batch_id", "in": "path", + "name": "segment_id", "required": true, "type": "string" } ], - "get": { - "description": "Validate whether or not a batch id is valid.\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": "Validate batch ID", + "patch": { "consumes": [ "application/json" ], + "description": "Update a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Update a segment", + "parameters": [ + { + "description": "The ID of the segment you are updating.", + "in": "query", + "name": "segment_id", + "type": "string" + }, + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "conditions": { + "description": "The conditions by which this segment should be created.", + "items": { + "$ref": "#/definitions/contactdb_segments_conditions" + }, + "type": "array" + }, + "list_id": { + "description": "The list ID you would like this segment to be built from.", + "type": "number" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + } + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "$ref": "#/definitions/mail_batch_id" - }, "examples": { "application/json": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" + "conditions": [ + { + "and_or": "", + "field": "last_name", + "operator": "eq", + "value": "Miller" + } + ], + "id": 5, + "list_id": 5, + "name": "The Millers", + "recipient_count": 1 } + }, + "schema": { + "$ref": "#/definitions/contactdb_segments" } }, "400": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ { - "field": null, - "message": "invalid batch id" + "message": "request body is not valid json" + }, + { + "message": "invalid value is passed into one of the request body parameters" + }, + { + "message": "segment id is not valid", + "segment_id": "segment_id" + }, + { + "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" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } }, "401": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "description": "", "examples": { "application/json": { "errors": [ @@ -8956,70 +7769,91 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "Validate whether or not a batch id is valid", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/user/profile": { - "parameters": [], - "patch": { - "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)\n\nIt 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": "Update a user's profile", + "/contactdb/segments/{segment_id}/recipients": { + "get": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "List all of the recipients in a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List Recipients On a Segment", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/user_profile" - } + "in": "query", + "name": "page", + "type": "integer" }, { - "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" + "in": "query", + "name": "page_size", + "type": "integer" } ], + "produces": [ + "application/json" + ], "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" + "recipients": [ + { + "created_at": 1422313607, + "custom_fields": [ + { + "id": 23, + "name": "pet", + "type": "text", + "value": "Indiana" + } + ], + "email": "jones@example.com", + "first_name": null, + "id": "YUBh", + "last_clicked": null, + "last_emailed": null, + "last_name": "Jones", + "last_opened": null, + "updated_at": 1422313790 + } + ] } + }, + "schema": { + "properties": { + "recipients": { + "items": { + "$ref": "#/definitions/contactdb_recipient" + }, + "type": "array" + } + }, + "required": [ + "recipients" + ], + "title": "List Recipients On a Segment response", + "type": "object" } }, + "400": { + "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"" + }, "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ @@ -9029,1547 +7863,1799 @@ } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } + }, + "404": { + "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"" } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, + "parameters": [ + { + "in": "path", + "name": "segment_id", + "required": true, + "type": "integer" + } + ] + }, + "/devices/stats": { "get": { - "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 a user's profile", "consumes": [ "application/json" ], + "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": "Retrieve email statistics by device type.", + "parameters": [ + { + "description": "The end date of the statistics to retrieve. Defaults to today.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "How many results to include on each page.", + "in": "query", + "name": "limit", + "required": false, + "type": "integer" + }, + { + "description": "How many results to exclude.", + "in": "query", + "name": "offset", + "required": false, + "type": "integer" + }, + { + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + }, + { + "description": "The starting date of the statistics to retrieve.", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "title": "GET User Profile response", - "type": "object", - "properties": { - "address": { - "type": "string", - "description": "The user's address." + "examples": { + "application/json": [ + { + "date": "2015-10-11", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-12", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-13", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-14", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-15", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-16", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-17", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-18", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-19", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-20", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-21", + "stats": [ + { + "metrics": { + "opens": 1, + "unique_opens": 1 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-22", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-23", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-10-24", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "address2": { - "type": "string", - "description": "The second line of the user's address." + { + "date": "2015-10-25", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "city": { - "type": "string", - "description": "The user's city." + { + "date": "2015-10-26", + "stats": [ + { + "metrics": { + "opens": 2, + "unique_opens": 2 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "company": { - "type": "string", - "description": "The name of the user's company." + { + "date": "2015-10-27", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "country": { - "type": "string", - "description": "The user's country." + { + "date": "2015-10-28", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "first_name": { - "type": "string", - "description": "The user's first name." + { + "date": "2015-10-29", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "last_name": { - "type": "string", - "description": "The user's last name." + { + "date": "2015-10-30", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "phone": { - "type": "string", - "description": "The user's phone number." + { + "date": "2015-10-31", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "state": { - "type": "string", - "description": "The user's state." + { + "date": "2015-11-01", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "website": { - "type": "string", - "description": "The user's website URL." + { + "date": "2015-11-02", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] }, - "zip": { - "type": "string", - "description": "The user's zip code." - } - }, - "required": [ - "address", - "city", - "company", - "country", - "first_name", - "last_name", - "phone", - "state", - "website", - "zip" - ] - }, - "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": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/campaigns/{campaign_id}/schedules/test": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "post": { - "description": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Send a Test Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "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" - ] - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "title": "Send a Test Campaign request", - "type": "object", - "properties": { - "to": { - "type": "string" + { + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-04", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-05", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-06", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-07", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-08", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-09", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] + }, + { + "date": "2015-11-10", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Webmail", + "type": "device" + } + ] } - }, - "required": [ - "to" ] - } - }, - "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"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" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } + "items": { + "$ref": "#/definitions/advanced_stats_opens" + }, + "type": "array" } } }, - "summary": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", "security": [ { "Authorization": [] } - ] - } + ], + "summary": "" + }, + "parameters": [] }, - "/ips": { - "parameters": [], + "/geo/stats": { "get": { - "description": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabel info.\nThe start_date field corresponds to when warmup started for that IP.", - "operationId": "List all IPs", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "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": "Retrieve email statistics by country and state/province.", "parameters": [ { - "name": "ip", + "description": "How many results to include on each page.", "in": "query", - "description": "The IP address to get", - "type": "string" + "name": "limit", + "required": false, + "type": "integer" }, { - "name": "exclude_whitelabels", + "description": "How many results to exclude.", "in": "query", - "description": "Should we exclude whitelabels?", - "type": "boolean" + "name": "offset", + "required": false, + "type": "integer" }, { - "name": "subuser", + "description": "How you would like the statistics to be grouped. Must be either \"day\", \"week\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], "in": "query", - "description": "The subuser you are requesting for.", + "name": "aggregated_by", + "required": false, "type": "string" }, { - "name": "limit", + "description": "The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD", "in": "query", - "description": "The number of IPs you want returned at the same time.", - "type": "integer" + "name": "start_date", + "required": true, + "type": "string" }, { - "name": "offset", + "description": "The end date of the statistics to retrieve. ", "in": "query", - "description": "The offset for the number of IPs that you are requesting.", - "type": "integer" + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "The country you would like to see statistics for. Currently only supported for US and CA.", + "enum": [ + "US", + "CA" + ], + "in": "query", + "name": "country", + "required": false, + "type": "string" } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "subusers": { - "type": "array", - "items": { - "type": "string" + "examples": { + "application/json": [ + { + "date": "2015-10-11", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-12", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-13", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-14", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-15", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-16", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-17", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-18", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" } - }, - "rdns": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" + ] + }, + { + "date": "2015-10-19", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": [ - "number", - "null" - ] - }, - "whitelabeled": { - "type": "boolean" - } - } - } - }, - "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 + "date": "2015-10-20", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-21", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 1, + "unique_clicks": 0, + "unique_opens": 1 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-22", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-23", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-24", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-25", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-26", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-27", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-28", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-29", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-30", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-10-31", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-11-02", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] + }, + { + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "TX", + "type": "province" + } + ] }, { - "ip": "127.0.0.1", - "subusers": [], - "pools": [], - "warmup": false, - "start_date": null, - "whitelabeled": false - } - ] - } - } - }, - "summary": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabe", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links/default": { - "parameters": [], - "get": { - "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:\nCheck out our spring line!
", - "plain_content": "Check out our spring line!", - "status": "Draft" - }, + "errors": [ { - "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" + "field": null, + "message": "authorization required" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "Returns campaigns in reverse order they were created (newest first)\nReturns an empty array if no campaigns exist", "security": [ { "Authorization": [] } - ] + ], + "summary": "Validate whether or not a batch id is valid" }, - "post": { - "description": "Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\n\nNote: 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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Create a Campaign", + "parameters": [ + { + "in": "path", + "name": "batch_id", + "required": true, + "type": "string" + } + ] + }, + "/mail_settings": { + "get": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "", + "operationId": "Get all mail settings", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/campaign_request" - } + "in": "query", + "name": "limit", + "type": "integer" + }, + { + "in": "query", + "name": "offset", + "type": "integer" } ], + "produces": [ + "application/json" + ], "responses": { - "201": { + "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" - } - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"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" - }, + "result": [ { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" + "description": "Address / domains that should never have email suppressed.", + "enabled": false, + "name": "address_whitelist", + "title": "Address Whitelist" }, { - "field": "sender_id", - "message": "sender_id does not exist" + "description": "Automatically BCC an address for every e-mail sent.", + "enabled": false, + "name": "bcc", + "title": "BCC" }, { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" + "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days.", + "enabled": false, + "name": "bounce_purge", + "title": "Bounce Purge" }, { - "field": "list_ids", - "message": "list_ids do not all exist" + "description": "Controls notifications for events, such as bounces, clicks, and opens.", + "enabled": true, + "name": "event_notify", + "title": "Event Notification" }, { - "field": "segment_ids", - "message": "segment_ids do not all exist" + "description": "Allows you to add a custom footer to outgoing email.", + "enabled": false, + "name": "footer", + "title": "Footer" }, { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" + "description": "Allows you to forward bounces to a specific email address.", + "enabled": true, + "name": "forward_bounce", + "title": "Forward Bounce" }, { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" + "description": "Allows for a copy of spam reports to be forwarded to an email address.", + "enabled": false, + "name": "forward_spam", + "title": "Forward Spam" }, { - "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." + "description": "Allows you to customize your outgoing HTML emails.", + "enabled": true, + "name": "template", + "title": "Legacy Email Template" }, { - "field": null, - "message": "The JSON you have submitted cannot be parsed." + "description": "Convert your plain text emails to HTML.", + "enabled": false, + "name": "plain_content", + "title": "Plain Content" }, { - "field": null, - "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + "description": "Check outbound messages for spam content.", + "enabled": true, + "name": "spam_check", + "title": "Spam Checker" } ] } - } - }, - "401": { - "description": "", + }, "schema": { - "type": "object", - "properties": {} + "properties": { + "result": { + "items": { + "properties": { + "description": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "name": { + "type": "string" + }, + "title": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" } } }, - "summary": "{% info %}\nA campaign requires a title to be created.\nIn order to send or schedule the campaign, you will be required to", "security": [ { "Authorization": [] } - ] - } + ], + "summary": "" + }, + "parameters": [] }, - "/subusers/reputations": { - "parameters": [], + "/mail_settings/address_whitelist": { "get": { - "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": "Retrieve Subuser Reputations", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get address whitelist mail settings", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "usernames", - "in": "query", - "type": "string" - } - ], "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" + "examples": { + "application/json": { + "enabled": false, + "list": [ + "example.com" ] } }, - "examples": { - "application/json": [ - { - "username": "example_subuser", - "reputation": 99 + "schema": { + "$ref": "#/definitions/mail_settings_address_whitelabel" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update address whitelist mail settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "enabled": { + "type": "boolean" }, - { - "username": "example_subuser2", - "reputation": 95.2 + "list": { + "items": { + "type": "string" + }, + "type": "array" } - ] + }, + "type": "object" } - }, - "401": { + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { "description": "", + "examples": { + "application/json": { + "enabled": true, + "list": [ + "email1@example.com" + ] + } + }, "schema": { - "type": "object", - "properties": {} + "$ref": "#/definitions/mail_settings_address_whitelabel" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/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" - } - ], + "/mail_settings/bcc": { "get": { - "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": "Retrieve an IP whitelabel", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get BCC mail settings", + "parameters": [], "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" - } + "email": "example@example.com", + "enabled": false } - } - }, - "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" - ] }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Whitelabel ip not found." - } - ] - } + "schema": { + "$ref": "#/definitions/mail_settings_bcc" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" }, - "delete": { - "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 an IP whitelabel", + "parameters": [], + "patch": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Update BCC mail settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/mail_settings::patch" + } + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "404": { + "200": { "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." - } - ] + "email": "example@example.com", + "enabled": false } + }, + "schema": { + "$ref": "#/definitions/mail_settings::patch" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, "/mail_settings/bounce_purge": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update bounce purge mail settings", + "get": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Get bounce purge mail settings", + "parameters": [], "produces": [ "application/json" ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "enabled": false, + "hard_bounces": null, + "soft_bounces": 1234 + } + }, + "schema": { + "$ref": "#/definitions/mail_settings_bounce_purge" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update bounce purge mail settings", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "type": "object", "properties": { "enabled": { "type": "boolean" @@ -11070,759 +10094,617 @@ "soft_bounces": { "type": "integer" } - } + }, + "type": "object" } } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" - }, "examples": { "application/json": { "enabled": false, "hard_bounces": null, "soft_bounces": null } + }, + "schema": { + "$ref": "#/definitions/mail_settings_bounce_purge" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - }, + ], + "summary": "" + } + }, + "/mail_settings/footer": { "get": { - "description": "", - "operationId": "Get bounce purge mail settings", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get footer mail settings [params can be null?]", + "parameters": [], "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 + "enabled": true, + "html_content": "Example HTML content", + "plain_content": "Example plain content" } + }, + "schema": { + "$ref": "#/definitions/mail_settings_footer" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/whitelabel/links": { + ], + "summary": "" + }, "parameters": [], - "post": { - "description": "**This endpoint allows you to create a new 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": "Create a Link Whitelabel", + "patch": { "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "", + "operationId": "Update footer mail settings", "parameters": [ { - "name": "limit", - "in": "query", - "description": "Number of domains to return.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset.", - "type": "integer" - }, - { - "name": "body", "in": "body", + "name": "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" - ] + "$ref": "#/definitions/mail_settings_footer" } } ], + "produces": [ + "application/json" + ], "responses": { - "201": { + "200": { "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" - } - } + "enabled": true, + "html_content": "Example HTML content", + "plain_content": "Example plain content" } + }, + "schema": { + "$ref": "#/definitions/mail_settings_footer" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - }, + ], + "summary": "" + } + }, + "/mail_settings/forward_bounce": { "get": { - "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": "Retrieve all link whitelabels", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get forward bounce mail settings", + "parameters": [], "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": { + "email": null, + "enabled": false } }, - "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" - } - } + "schema": { + "$ref": "#/definitions/mail_settings_forward_bounce" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update forward bounce mail settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "email": { + "type": "string" }, - { - "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" - } - } + "enabled": { + "type": "boolean" } - ] + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "email": "", + "enabled": true + } + }, + "schema": { + "$ref": "#/definitions/mail_settings_forward_bounce" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/user/settings/enforced_tls": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Change the Enforced TLS settings", + "/mail_settings/forward_spam": { + "get": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Get forward spam mail settings", + "parameters": [], "produces": [ "application/json" ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "email": "", + "enabled": true + } + }, + "schema": { + "$ref": "#/definitions/mail_settings_forward_spam" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update forward spam mail settings", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "type": "object", - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } - } + "$ref": "#/definitions/mail_settings_forward_spam" } } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } - } - }, "examples": { "application/json": { - "require_tls": true, - "require_valid_cert": false + "email": "", + "enabled": false } + }, + "schema": { + "$ref": "#/definitions/mail_settings_forward_spam" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - }, + ], + "summary": "" + } + }, + "/mail_settings/plain_content": { "get": { - "description": "", - "operationId": "Get the current Enforced TLS settings.", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get plain content mail settings", + "parameters": [], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", + "examples": { + "application/json": { + "enabled": false + } + }, "schema": { - "type": "object", "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { + "enabled": { "type": "boolean" } - } - }, - "examples": { - "application/json": { - "require_tls": false, - "require_valid_cert": false - } + }, + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/mail/batch": { + ], + "summary": "" + }, "parameters": [], - "post": { - "description": "Generate a new Batch ID to associate 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": "Create a batch ID", + "patch": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Update plain content mail settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "enabled": { + "type": "boolean" + } + }, + "type": "object" + } + } + ], "produces": [ "application/json" ], - "parameters": [], "responses": { - "201": { + "200": { "description": "", - "schema": { - "$ref": "#/definitions/mail_batch_id" - }, "examples": { "application/json": { - "batch_id": "YOUR_BATCH_ID" + "enabled": false } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "schema": { + "properties": { + "enabled": { + "type": "boolean" + } + }, + "type": "object" } } }, - "summary": "Generate a new Batch ID to associate with scheduled sends", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/subusers/{subuser_name}/ips": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "put": { - "description": "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)", - "operationId": "Update IPs assigned to a subuser", + "/mail_settings/spam_check": { + "get": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Get spam check mail settings", + "parameters": [], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "items": { - "type": "string", - "format": "ipv4" - } - } - } - }, "examples": { "application/json": { - "ips": [ - "127.0.0.1" - ] + "enabled": false, + "max_score": 6, + "url": "http://example.com" } + }, + "schema": { + "$ref": "#/definitions/mail_settings_spam_check" } - }, - "401": { - "description": "", + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update spam check mail settings", + "parameters": [ + { + "in": "body", + "name": "body", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "properties": { + "enabled": { + "type": "boolean" + }, + "max_score": { + "type": "integer" + }, + "url": { + "type": "string" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": false, + "max_score": 6, + "url": "http://example.com" } + }, + "schema": { + "$ref": "#/definitions/mail_settings_spam_check" } } }, + "security": [ + { + "Authorization": [] + } + ], "summary": "" } }, - "/api_keys": { - "parameters": [], + "/mail_settings/template": { "get": { - "description": "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": "List all API Keys belonging to the authenticated user", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get template mail settings", + "parameters": [], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "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" - } - ] + "enabled": false, + "html_content": "<% body %>Example
\n" } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "schema": { + "properties": { + "enabled": { + "type": "boolean" + }, + "html_content": { + "type": "string" + } + }, + "type": "object" } } }, - "summary": "**List all API Keys belonging to the authenticated user**\n\nThe API Keys feature allows customers to be able to generate ", "security": [ { "Authorization": [] } - ] - } - }, - "/whitelabel/domains/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "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 “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.\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": "Validate a domain whitelabel.", + ], + "summary": "" + }, + "parameters": [], + "patch": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Update template mail settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "enabled": { + "type": "boolean" + }, + "html_content": { + "type": "string" + } + }, + "type": "object" + } + } + ], "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 - } - } + "enabled": false, + "html_content": "<% body %>Example
\n" } - } - }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object", - "properties": {} - } - }, - "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" - ] - } + "enabled": { + "type": "boolean" + }, + "html_content": { + "type": "string" } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting TXT" - } - ] - } + }, + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/devices/stats": { - "parameters": [], + "/mailbox_providers/stats": { "get": { - "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": "Retrieve email statistics by device type.", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "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": "Retrieve email statistics by mailbox provider.", "parameters": [ { - "name": "end_date", + "description": "The number of results to include on each page.", "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", + "name": "limit", "required": false, - "type": "string" + "type": "integer" }, { - "name": "limit", + "description": "The number of results to exclude.", "in": "query", - "description": "How many results to include on each page.", + "name": "offset", "required": false, "type": "integer" }, { - "name": "offset", + "description": "How to group the stats. Must be either \"day\", \"wee\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], "in": "query", - "description": "How many results to exclude.", + "name": "aggregated_by", "required": false, - "type": "integer" + "type": "string" }, { - "name": "aggregated_by", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "name": "start_date", + "required": true, + "type": "string" + }, + { + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "end_date", "required": false, "type": "string" }, { - "name": "start_date", + "description": "The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times.", "in": "query", - "description": "The starting date of the statistics to retrieve.", - "required": true, + "name": "mailbox_providers", + "required": false, "type": "string" } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - }, "examples": { "application/json": [ { "date": "2015-10-11", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11830,12 +10712,20 @@ "date": "2015-10-12", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11843,12 +10733,20 @@ "date": "2015-10-13", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11856,12 +10754,20 @@ "date": "2015-10-14", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11869,12 +10775,20 @@ "date": "2015-10-15", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11882,12 +10796,20 @@ "date": "2015-10-16", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11895,12 +10817,20 @@ "date": "2015-10-17", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11908,12 +10838,20 @@ "date": "2015-10-18", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11921,12 +10859,20 @@ "date": "2015-10-19", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11934,12 +10880,20 @@ "date": "2015-10-20", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11947,12 +10901,20 @@ "date": "2015-10-21", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 1, + "drops": 0, "opens": 1, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 1 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11960,12 +10922,20 @@ "date": "2015-10-22", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11973,12 +10943,20 @@ "date": "2015-10-23", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11986,12 +10964,20 @@ "date": "2015-10-24", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -11999,12 +10985,20 @@ "date": "2015-10-25", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -12012,12 +11006,20 @@ "date": "2015-10-26", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 2, + "drops": 0, "opens": 2, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 2 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, @@ -12025,240 +11027,590 @@ "date": "2015-10-27", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" + } + ] + }, + { + "date": "2015-10-28", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, + "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "Gmail", + "type": "mailbox_provider" + } + ] + }, + { + "date": "2015-10-29", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, + "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-10-28", + "date": "2015-10-30", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-10-29", + "date": "2015-10-31", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-10-30", + "date": "2015-11-01", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-10-31", + "date": "2015-11-02", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-01", + "date": "2015-11-03", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-02", + "date": "2015-11-04", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-03", + "date": "2015-11-05", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-04", + "date": "2015-11-06", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-05", + "date": "2015-11-07", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-06", + "date": "2015-11-08", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-07", + "date": "2015-11-09", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] }, { - "date": "2015-11-08", + "date": "2015-11-10", "stats": [ { - "type": "device", - "name": "Webmail", "metrics": { + "blocks": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, + "unique_clicks": 0, "unique_opens": 0 - } + }, + "name": "Gmail", + "type": "mailbox_provider" } ] + } + ] + }, + "schema": { + "items": { + "$ref": "#/definitions/advanced_stats_mailbox_provider" + }, + "type": "array" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/partner_settings": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Returns a list of all partner settings.", + "parameters": [ + { + "description": "The number of settings to return per page.", + "in": "query", + "name": "limit", + "type": "integer" + }, + { + "description": "The paging offset.", + "in": "query", + "name": "offset", + "type": "integer" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "result": [ + { + "description": "A description of a partner.", + "enabled": true, + "name": "partner_name", + "title": "Partner title" + } + ] + } + }, + "schema": { + "properties": { + "result": { + "items": { + "properties": { + "description": { + "description": "A description of this partner setting.", + "type": "string" + }, + "enabled": { + "description": "Indicates if this partner setting has been enabled.", + "type": "boolean" + }, + "name": { + "description": "The name of the partner setting.", + "type": "string" + }, + "title": { + "description": "The title of the partner.", + "type": "string" + } + }, + "required": [ + "title", + "enabled", + "name", + "description" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/partner_settings/new_relic": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Returns all New Relic partner settings.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "enable_subuser_statistics": false, + "enabled": true, + "license_key": "" + } + }, + "schema": { + "$ref": "#/definitions/partner_settings_new_relic" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to update or change your 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": "Updates New Relic partner settings.", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "enable_subuser_statistics": { + "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard.", + "type": "boolean" }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] + "enabled": { + "description": "Indicates if this partner setting is enabled.", + "type": "boolean" }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] + "license_key": { + "description": "The license key for your New Relic account.", + "type": "string" } - ] + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "enable_subuser_statistics": true, + "enabled": true, + "license_key": "" + } + }, + "schema": { + "$ref": "#/definitions/partner_settings_new_relic" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/scopes": { - "parameters": [], + "/partner_settings/sendwithus": { "get": { - "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’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": "Returns a list of scopes for which this user has access.", "consumes": [ "application/json" ], + "description": "", + "operationId": "Get SendWithUs Settings", + "parameters": [], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", "schema": { - "type": "object", + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update SendWithUs Settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { "properties": { - "scopes": { - "type": "array", - "description": "The list of scopes for which this user has access.", - "uniqueItems": true, - "items": { - "type": "string" + "body": { + "description": "", + "schema": { + "type": "object" } } }, "required": [ - "scopes" + "body" ] - }, + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "summary": "" + } + }, + "/scopes": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Returns a list of scopes for which this user has access.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", "examples": { "application/json": { "scopes": [ @@ -12267,6012 +11619,6660 @@ "alerts.read" ] } + }, + "schema": { + "properties": { + "scopes": { + "description": "The list of scopes for which this user has access.", + "items": { + "type": "string" + }, + "type": "array", + "uniqueItems": true + } + }, + "required": [ + "scopes" + ], + "type": "object" } }, "401": { "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, "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." + "description": "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required.", + "type": "null" }, "message": { - "type": "string", - "description": "Explains why the scopes cannot be returned." + "description": "Explains why the scopes cannot be returned.", + "type": "string" } }, "required": [ "message" - ] - } + ], + "type": "object" + }, + "type": "array" } }, "required": [ "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + ], + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } + ], + "summary": "" + }, + "parameters": [] }, - "/geo/stats": { - "parameters": [], + "/stats": { "get": { - "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": "Retrieve email statistics by country and state/province.", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "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": "Retrieve global email statistics", "parameters": [ { - "name": "limit", + "description": "The number of results to return.", "in": "query", - "description": "How many results to include on each page.", + "name": "limit", "required": false, "type": "integer" }, { - "name": "offset", + "description": "The point in the list to begin retrieving results.", "in": "query", - "description": "How many results to exclude.", + "name": "offset", "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", + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", "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, + "name": "aggregated_by", + "required": false, "type": "string" }, { - "name": "end_date", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", "in": "query", - "description": "The end date of the statistics to retrieve. ", - "required": false, + "name": "start_date", + "required": true, "type": "string" }, { - "name": "country", + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", "in": "query", - "description": "The country you would like to see statistics for. Currently only supported for US and CA.", + "name": "end_date", "required": false, - "type": "string", - "enum": [ - "US", - "CA" - ] + "type": "string" } ], + "produces": [ + "application/json" + ], "responses": { "200": { "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_country" - } - }, "examples": { "application/json": [ { - "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", + "date": "2015-11-03", "stats": [ { - "type": "province", - "name": "TX", "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 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 1, - "unique_clicks": 0, - "unique_opens": 1 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] }, { - "date": "2015-10-22", + "date": "2015-11-04", "stats": [ { - "type": "province", - "name": "TX", "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 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] }, { - "date": "2015-10-23", + "date": "2015-11-05", "stats": [ { - "type": "province", - "name": "TX", "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 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] }, { - "date": "2015-10-24", + "date": "2015-11-06", "stats": [ { - "type": "province", - "name": "TX", "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 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] }, { - "date": "2015-10-25", + "date": "2015-11-07", "stats": [ { - "type": "province", - "name": "TX", "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 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] }, { - "date": "2015-10-26", + "date": "2015-11-08", "stats": [ { - "type": "province", - "name": "TX", "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 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] }, { - "date": "2015-10-27", + "date": "2015-11-09", "stats": [ { - "type": "province", - "name": "TX", "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 + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } ] + } + ] + }, + "schema": { + "items": { + "properties": { + "date": { + "description": "The date the stats were gathered.", + "type": "string" + }, + "stats": { + "description": "The individual email activity stats.", + "items": { + "properties": { + "metrics": { + "properties": { + "blocks": { + "description": "The number of emails that were not allowed to be delivered by ISPs.", + "type": "integer" + }, + "bounce_drops": { + "description": "The number of emails that were dropped because of a bounce.", + "type": "integer" + }, + "bounces": { + "description": "The number of emails that bounced instead of being delivered.", + "type": "integer" + }, + "clicks": { + "description": "The number of links that were clicked in your emails.", + "type": "integer" + }, + "deferred": { + "description": "The number of emails that temporarily could not be delivered. ", + "type": "integer" + }, + "delivered": { + "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient.", + "type": "integer" + }, + "invalid_emails": { + "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid.", + "type": "integer" + }, + "opens": { + "description": "The total number of times your emails were opened by recipients.", + "type": "integer" + }, + "processed": { + "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.", + "type": "integer" + }, + "requests": { + "description": "The number of emails that were requested to be delivered.", + "type": "integer" + }, + "spam_report_drops": { + "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam.", + "type": "integer" + }, + "spam_reports": { + "description": "The number of recipients who marked your email as spam.", + "type": "integer" + }, + "unique_clicks": { + "description": "The number of unique recipients who clicked links in your emails.", + "type": "integer" + }, + "unique_opens": { + "description": "The number of unique recipients who opened your emails.", + "type": "integer" + }, + "unsubscribe_drops": { + "description": "The number of emails dropped due to a recipient unsubscribing from your emails.", + "type": "integer" + }, + "unsubscribes": { + "description": "The number of recipients who unsubscribed from your emails.", + "type": "integer" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "date", + "stats" + ], + "type": "object" + }, + "type": "array" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/subusers": { + "get": { + "consumes": [ + "application/json" + ], + "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": "List all Subusers", + "parameters": [ + { + "description": "The username of this subuser.", + "in": "query", + "name": "username", + "type": "string" + }, + { + "description": "The number of results you would like to get in each request.", + "in": "query", + "name": "limit", + "type": "number" + }, + { + "description": "The number of subusers to skip.", + "in": "query", + "name": "offset", + "type": "number" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "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" + } + ] + }, + "schema": { + "items": { + "$ref": "#/definitions/subuser" + }, + "type": "array" + } + }, + "401": { + "description": "Unexpected error in API call. See HTTP response body for details.", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "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": "Create Subuser", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "email": { + "description": "The email address of the subuser.", + "format": "email", + "type": "string" + }, + "ips": { + "description": "The IP addresses that should be assigned to this subuser.", + "items": { + "format": "ipv4", + "type": "string" + }, + "type": "array" + }, + "password": { + "description": "The password this subuser will use when logging into SendGrid.", + "type": "string" + }, + "username": { + "description": "The username for this subuser.", + "type": "string" + } + }, + "required": [ + "username", + "email", + "password", + "ips" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "authorization_token": "", + "credit_allocation": { + "type": "unlimited" }, + "email": "example@example.com", + "signup_session_token": "", + "user_id": 1234, + "username": "example_subuser" + } + }, + "schema": { + "$ref": "#/definitions/subuser_post" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "username exists" + }, + { + "message": "unable to validate IPs at this time" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "403": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "you dont have permission to access this resource" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "500": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "unable to validate IPs at this time" + } + ] + } + }, + "schema": { + "properties": {}, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/subusers/reputations": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve Subuser Reputations", + "parameters": [ + { + "in": "query", + "name": "usernames", + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ { - "date": "2015-10-28", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "reputation": 99, + "username": "example_subuser" }, { - "date": "2015-10-29", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "reputation": 95.2, + "username": "example_subuser2" + } + ] + }, + "schema": { + "items": { + "properties": { + "reputation": { + "description": "The sender reputation this subuser has attained.", + "type": "number" + }, + "username": { + "description": "The subuser that has this reputation.f", + "type": "string" + } }, + "required": [ + "reputation", + "username" + ], + "type": "object" + }, + "type": "array" + } + }, + "401": { + "description": "", + "schema": { + "properties": {}, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/subusers/stats": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve email statistics for your subusers.", + "parameters": [ + { + "description": "Limits the number of results returned per page.", + "in": "query", + "name": "limit", + "required": false, + "type": "integer" + }, + { + "description": "The point in the list to begin retrieving results from.", + "in": "query", + "name": "offset", + "required": false, + "type": "integer" + }, + { + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "enum": [ + "day", + "week", + "month" + ], + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + }, + { + "description": "The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers.", + "in": "query", + "name": "subusers", + "required": true, + "type": "string" + }, + { + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" + }, + { + "description": "The end date of the statistics to retrieve. Defaults to today.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ { - "date": "2015-10-30", + "date": "2015-10-01", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-10-31", + "date": "2015-10-02", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-01", + "date": "2015-10-03", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-02", + "date": "2015-10-04", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-03", + "date": "2015-10-05", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-04", + "date": "2015-10-06", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-05", + "date": "2015-10-07", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-06", + "date": "2015-10-08", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-07", + "date": "2015-10-09", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] }, { - "date": "2015-11-08", + "date": "2015-10-10", "stats": [ { - "type": "province", - "name": "TX", "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 - } + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "Matt_subuser", + "type": "subuser" } ] + } + ] + }, + "schema": { + "$ref": "#/definitions/stats" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/subusers/stats/sums": { + "get": { + "consumes": [ + "application/json" + ], + "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": " Retrieve the totals for each email statistic metric for all subusers.", + "parameters": [ + { + "description": "The direction you want to sort. ", + "enum": [ + "desc", + "asc" + ], + "in": "query", + "name": "sort_by_direction", + "required": false, + "type": "string" + }, + { + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" + }, + { + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + }, + { + "description": "Limits the number of results returned per page.", + "in": "query", + "name": "limit", + "required": false, + "type": "integer" + }, + { + "description": "The point in the list to begin retrieving results from.", + "in": "query", + "name": "offset", + "required": false, + "type": "integer" + }, + { + "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + }, + { + "description": "The metric that you want to sort by. Must be a single metric.", + "in": "query", + "name": "sort_by_metric", + "required": false, + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "date": "2015-10-11", + "stats": [] + } + }, + "schema": { + "$ref": "#/definitions/category_stats" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/subusers/{subuser_name}": { + "delete": { + "consumes": [ + "application/json" + ], + "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 a subuser", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "", + "schema": { + "properties": {}, + "type": "object" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [ + { + "in": "path", + "name": "subuser_name", + "required": true, + "type": "string" + } + ], + "patch": { + "consumes": [ + "application/json" + ], + "description": "This endpoint allows you to enable or disable a subuser.\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": "Enable/disable a subuser", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "disabled": { + "description": "Whether or not this subuser is disabled. True means disabled, False means enabled.", + "type": "boolean" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "", + "schema": { + "properties": {}, + "type": "object" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid username" + }, + { + "message": "no fields provided" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "500": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "unable to enable user" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/subusers/{subuser_name}/ips": { + "parameters": [ + { + "in": "path", + "name": "subuser_name", + "required": true, + "type": "string" + } + ], + "put": { + "consumes": [ + "application/json" + ], + "description": "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)", + "operationId": "Update IPs assigned to a subuser", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "ips": [ + "127.0.0.1" + ] + } + }, + "schema": { + "properties": { + "ips": { + "items": { + "format": "ipv4", + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "summary": "" + } + }, + "/subusers/{subuser_name}/monitor": { + "delete": { + "consumes": [ + "application/json" + ], + "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 monitor settings", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "", + "schema": { + "properties": {}, + "type": "object" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "No monitor settings for this user" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "summary": "" + }, + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve monitor settings for a subuser", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "email": "example@example.com", + "frequency": 500 + } + }, + "schema": { + "$ref": "#/definitions/monitor" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "No monitor settings for this user" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [ + { + "in": "path", + "name": "subuser_name", + "required": true, + "type": "string" + } + ], + "post": { + "consumes": [ + "application/json" + ], + "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": "Create monitor settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/monitor" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "email": "example@example.com", + "frequency": 50000 + } + }, + "schema": { + "$ref": "#/definitions/monitor" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "User already has a monitor" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "put": { + "consumes": [ + "application/json" + ], + "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": "Update Monitor Settings for a subuser", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/monitor" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "email": "example@example.com", + "frequency": 500 + } + }, + "schema": { + "$ref": "#/definitions/monitor" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": "email", + "message": "Email is required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/suppression/bounces": { + "delete": { + "consumes": [ + "application/json" + ], + "description": "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete 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)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes.", + "operationId": "Delete bounces", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "delete_all": { + "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter.", + "type": "boolean" }, + "emails": { + "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "get": { + "consumes": [ + "application/json" + ], + "description": "Bounces 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": "List all bounces", + "parameters": [ + { + "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", + "in": "query", + "name": "start_time", + "type": "number" + }, + { + "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" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ { - "date": "2015-11-09", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "created": 1250337600, + "email": "example@example.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" }, { - "date": "2015-11-10", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "created": 1250337600, + "email": "example@example.com", + "reason": "550 5.1.1Something something unsubscribe <% %> something something
\n", + "landing": "subscribehere
\n", + "plain_content": "Something something unsubscribe <% %> something something", + "replace": "thetag", + "url": "" + } + }, + "schema": { + "properties": { + "enabled": { + "type": "boolean" }, - { - "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 - } - } - ] + "html_content": { + "type": "string" }, - { - "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 - } - } - ] + "landing": { + "type": "string" + }, + "plain_content": { + "type": "string" + }, + "replace": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update Subscription Tracking Settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "enabled": { + "type": "boolean" }, - { - "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 - } - } - ] + "html_content": { + "type": "string" }, - { - "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 - } - } - ] + "landing": { + "type": "string" }, - { - "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 - } - } - ] + "plain_content": { + "type": "string" }, - { - "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 - } - } - ] + "replace": { + "type": "string" }, - { - "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 - } - } - ] + "url": { + "type": "string" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "enabled": true, + "html_content": "html content", + "landing": "landing page html", + "plain_content": "text content", + "replace": "replacement tag", + "url": "url" + } + }, + "schema": { + "properties": { + "enabled": { + "type": "boolean" }, - { - "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 - } - } - ] + "html_content": { + "type": "string" }, - { - "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 - } - } - ] + "landing": { + "type": "string" + }, + "plain_content": { + "type": "string" + }, + "replace": { + "type": "string" + }, + "url": { + "type": "string" } - ] + }, + "type": "object" } } }, - "summary": "", "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": { - "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": "Validate a Link Whitelabel", + ], + "summary": "" + } + }, + "/user/account": { + "get": { "consumes": [ "application/json" ], + "description": "Your user's account information includes the user's account type and reputation.", + "operationId": "Get a user's account information.", + "parameters": [], "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 - } - } + "reputation": 100, + "type": "paid" } - } - }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details." - }, - "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" - ] - } + "reputation": { + "description": "The sender reputation for this user.", + "type": "number" + }, + "type": { + "description": "The type of account for this user.", + "enum": [ + "free", + "paid" + ], + "type": "string" } }, "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting CNAME" - } - ] - } + "type", + "reputation" + ], + "title": "GET User Account response", + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } + ], + "summary": "" + }, + "parameters": [] }, - "/ips/pools/{pool_name}/ips/{ip}": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "ip", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "", - "operationId": "Remove an IP address from a pool.", + "/user/profile": { + "get": { "consumes": [ "application/json" ], - "produces": [], + "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 a user's profile", "parameters": [], + "produces": [ + "application/json" + ], "responses": { - "204": { + "200": { + "description": "", + "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" + } + }, + "schema": { + "properties": { + "address": { + "description": "The user's address.", + "type": "string" + }, + "address2": { + "description": "The second line of the user's address.", + "type": "string" + }, + "city": { + "description": "The user's city.", + "type": "string" + }, + "company": { + "description": "The name of the user's company.", + "type": "string" + }, + "country": { + "description": "The user's country.", + "type": "string" + }, + "first_name": { + "description": "The user's first name.", + "type": "string" + }, + "last_name": { + "description": "The user's last name.", + "type": "string" + }, + "phone": { + "description": "The user's phone number.", + "type": "string" + }, + "state": { + "description": "The user's state.", + "type": "string" + }, + "website": { + "description": "The user's website URL.", + "type": "string" + }, + "zip": { + "description": "The user's zip code.", + "type": "string" + } + }, + "required": [ + "address", + "city", + "company", + "country", + "first_name", + "last_name", + "phone", + "state", + "website", + "zip" + ], + "title": "GET User Profile response", + "type": "object" + } + }, + "401": { "description": "", "schema": { - "type": "object", - "properties": {} + "properties": {}, + "type": "object" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/ips/{ip_address}": { - "parameters": [ - { - "name": "ip_address", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "", - "operationId": "See which pools an IP address belongs to.", + ], + "summary": "" + }, + "parameters": [], + "patch": { "consumes": [ "application/json" ], + "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)\n\nIt 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": "Update a user's profile", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "$ref": "#/definitions/user_profile" + } + }, + { + "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": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "subusers": { - "type": "array", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": [ - "integer", - "null" - ] - }, - "whitelabeled": { - "type": "boolean" - } + "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" } }, + "schema": { + "$ref": "#/definitions/user_profile" + } + }, + "401": { + "description": "", "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 + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "" } }, - "/ips/pools/{pool_name}/ips": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "", - "operationId": "Add an IP to a pool", + "/user/scheduled_sends": { + "get": { "consumes": [ "application/json" ], + "description": "Get 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 all scheduled sends", + "parameters": [], "produces": [ "application/json" ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - } - } - } - } - ], "responses": { - "201": { + "200": { "description": "", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "start_date": { - "type": "integer" + "examples": { + "application/json": [ + { + "batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg", + "status": "cancel" }, - "warmup": { - "type": "boolean" + { + "batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2", + "status": "cancel" } - } + ] }, + "schema": { + "items": { + "$ref": "#/definitions/user_scheduled_send_status" + }, + "type": "array" + } + }, + "401": { + "description": "", "examples": { "application/json": { - "ip": "000.00.00.0", - "pools": [ - "test1" - ], - "start_date": 1409616000, - "warmup": true + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/api_key": { + ], + "summary": "" + }, "parameters": [], "post": { - "description": "This will 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.\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", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], + "description": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.\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": "Cancel or pause a scheduled send", "parameters": [ { - "name": "body", "in": "body", + "name": "body", "schema": { - "type": "object", "properties": { - "name": { - "type": "string", - "description": "The name you will use to describe this API Key." + "batch_id": { + "description": "The batch ID is the identifier that your scheduled mail sends share.", + "pattern": "^[a-zA-Z0-9]", + "type": "string" }, - "scopes": { - "type": "array", - "description": "The individual permissions that you are giving to this API Key.", - "items": { - "type": "string" - } + "status": { + "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" + ], + "type": "string" } }, "required": [ - "name" - ] + "batch_id", + "status" + ], + "title": "Cancel or pause a scheduled send request", + "type": "object" } } ], + "produces": [ + "application/json" + ], "responses": { "201": { "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" - } - ] - } + "$ref": "#/definitions/user_scheduled_send_status" } }, "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, + "description": "\"\" : \"max limit reached\"\n\"batch_id\" : \"invalid batch id\"\n\"batch_id\" : \"a status for this batch id exists, try PATCH to update the status\"", "examples": { "application/json": { "errors": [ { - "field": "name", - "message": "missing required argument" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ + "field": null, + "message": "max limit reached" + }, { - "field": null, - "message": "authorization required" + "field": "batch_id", + "message": "invalid batch id" + }, + { + "field": "batch_id", + "message": "a status for this batch id exists, try PATCH to update the status" } ] } + }, + "schema": { + "properties": {}, + "type": "object" } }, - "403": { + "401": { "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "Cannot create more than 100 API Keys" + "message": "authorization required" } ] } + }, + "schema": { + "properties": {}, + "type": "object" } } }, - "summary": "**Generate a new API Key for the authenticated user**\n\nThis will create a new random API Key for the user. A JSON reques", "security": [ { "Authorization": [] } - ] + ], + "summary": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned." } }, - "/categories/stats": { - "parameters": [], - "get": { - "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": "Retrieve Email Statistics for Categories", + "/user/scheduled_sends/{batch_id}": { + "delete": { "consumes": [ "application/json" ], + "description": "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 a cancellation or pause of a scheduled send", + "parameters": [], "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", - "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": { + "204": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/category_stats" + "type": "null" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } }, - "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 - } - } - ] - } - ] + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/stats": { - "parameters": [], - "get": { - "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": "Retrieve global email statistics", - "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" }, + "404": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "batch id not found" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + } + }, + "security": [ { - "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" + "Authorization": [] } ], + "summary": "Delete the cancellation/pause of a scheduled send." + }, + "get": { + "consumes": [ + "application/json" + ], + "description": "Get 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": "Retrieve scheduled send", + "parameters": [], + "produces": [ + "application/json" + ], "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 - } - } - ] + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", + "status": "cancel" }, { - "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 - } - } - ] + "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", + "status": "pause" } ] + }, + "schema": { + "items": { + "$ref": "#/definitions/user_scheduled_send_status" + }, + "title": "Retrieve scheduled send response", + "type": "array" + } + }, + "401": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/categories/stats/sums": { - "parameters": [], - "get": { - "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": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", - "consumes": [ - "application/json" ], - "produces": [ + "summary": "Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations\na" + }, + "parameters": [ + { + "in": "path", + "name": "batch_id", + "required": true, + "type": "string" + } + ], + "patch": { + "consumes": [ "application/json" ], + "description": "Update the status 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": "Update user scheduled send information", "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" - }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "type": "string", - "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" - }, - { - "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" - ] + "in": "body", + "name": "body", + "schema": { + "properties": { + "status": { + "description": "The status you would like the scheduled send to have.", + "enum": [ + "cancel", + "pause" + ], + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + } } ], + "produces": [ + "application/json" + ], "responses": { - "200": { + "204": { "description": "", "schema": { - "type": "object", - "properties": { - "": { - "$ref": "#/definitions/category_stats" - } + "type": "null" + } + }, + "400": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "field": "status", + "message": "status must be either cancel or pause" + } + ] } }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "401": { + "description": "", "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" - }, + "errors": [ { - "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" + "field": null, + "message": "authorization required" + } + ] + } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"\" : \"batch id not found\"", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "batch id not found" } ] } + }, + "schema": { + "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] + ], + "summary": "Update the status of a scheduled send." } }, - "/user/webhooks/event/settings": { + "/user/settings/enforced_tls": { + "get": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Get the current Enforced TLS settings.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "require_tls": false, + "require_valid_cert": false + } + }, + "schema": { + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, "parameters": [], "patch": { + "consumes": [ + "application/json" + ], "description": "", - "operationId": "Update Event Notification Settings", + "operationId": "Change the Enforced TLS settings", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "require_tls": true, + "require_valid_cert": false + } + }, + "schema": { + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/user/webhooks/event/settings": { + "get": { "consumes": [ "application/json" ], + "description": "", + "operationId": "Retrieve Event Webhook Settings", + "parameters": [], "produces": [ "application/json" ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "bounce": true, + "click": true, + "deferred": true, + "delivered": true, + "dropped": true, + "enabled": true, + "group_resubscribe": true, + "group_unsubscribe": true, + "open": true, + "processed": true, + "spam_report": true, + "unsubscribe": true, + "url": "url" + } + }, + "schema": { + "properties": { + "bounce": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "group_resubscribe": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "processed": { + "type": "boolean" + }, + "spam_report": { + "type": "boolean" + }, + "unsubscribe": { + "type": "boolean" + }, + "url": { + "type": "string" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [], + "patch": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Update Event Notification Settings", "parameters": [ { - "name": "body", "in": "body", + "name": "body", + "schema": { + "properties": { + "bounce": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "group_resubscribe": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "processed": { + "type": "boolean" + }, + "spamreport": { + "type": "boolean" + }, + "unsubscribe": { + "type": "boolean" + }, + "url": { + "type": "string" + } + }, + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "bounce": true, + "click": true, + "deferred": true, + "delivered": true, + "dropped": true, + "enabled": true, + "group_resubscribe": true, + "group_unsubscribe": true, + "open": true, + "processed": true, + "spamreport": true, + "unsubscribe": true, + "url": "url" + } + }, "schema": { - "type": "object", "properties": { - "enabled": { + "bounce": { "type": "boolean" }, - "url": { - "type": "string" + "click": { + "type": "boolean" }, - "group_resubscribe": { + "deferred": { "type": "boolean" }, "delivered": { "type": "boolean" }, - "group_unsubscribe": { + "dropped": { "type": "boolean" }, - "spamreport": { + "enabled": { "type": "boolean" }, - "bounce": { + "group_resubscribe": { "type": "boolean" }, - "deferred": { + "group_unsubscribe": { "type": "boolean" }, - "unsubscribe": { + "open": { "type": "boolean" }, "processed": { "type": "boolean" }, - "open": { + "spamreport": { "type": "boolean" }, - "click": { + "unsubscribe": { "type": "boolean" }, - "dropped": { - "type": "boolean" + "url": { + "type": "string" } - } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/user/webhooks/event/test": { + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Test Event Notification Settings ", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "url": { + "type": "string" + } + }, + "type": "object" + } + } + ], + "produces": [], + "responses": { + "204": { + "description": "", + "schema": { + "properties": {}, + "type": "object" } } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/user/webhooks/parse/settings": { + "get": { + "consumes": [ + "application/json" + ], + "description": "", + "operationId": "Retrieve Parse API settings", + "parameters": [], + "produces": [ + "application/json" ], "responses": { "200": { "description": "", + "examples": { + "application/json": { + "result": [ + { + "hostname": "example.com", + "send_raw": false, + "spam_check": false, + "url": "http://example.com/example" + } + ] + } + }, "schema": { - "type": "object", "properties": { - "enabled": { - "type": "boolean" + "result": { + "items": { + "properties": { + "hostname": { + "type": "string" + }, + "send_raw": { + "type": "boolean" + }, + "spam_check": { + "type": "boolean" + }, + "url": { + "type": "string" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "parameters": [] + }, + "/user/webhooks/parse/stats": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieves Inbound Parse Webhook statistics.", + "parameters": [ + { + "description": "The number of statistics to return on each page.", + "in": "query", + "name": "limit", + "required": false, + "type": "string" + }, + { + "description": "The number of statistics to skip.", + "in": "query", + "name": "offset", + "required": false, + "type": "string" + }, + { + "description": "How you would like the statistics to by grouped. ", + "enum": [ + "day", + "week", + "month" + ], + "in": "query", + "name": "aggregated_by", + "required": false, + "type": "string" + }, + { + "description": "The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", + "in": "query", + "name": "start_date", + "required": true, + "type": "string" + }, + { + "description": "The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", + "in": "query", + "name": "end_date", + "required": false, + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "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 + } + } + ] }, - "url": { - "type": "string" + { + "date": "2015-10-17", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "group_resubscribe": { - "type": "boolean" + { + "date": "2015-10-18", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "delivered": { - "type": "boolean" + { + "date": "2015-10-19", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "group_unsubscribe": { - "type": "boolean" + { + "date": "2015-10-20", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "spamreport": { - "type": "boolean" + { + "date": "2015-10-21", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "bounce": { - "type": "boolean" + { + "date": "2015-10-22", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "deferred": { - "type": "boolean" + { + "date": "2015-10-23", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "unsubscribe": { - "type": "boolean" + { + "date": "2015-10-24", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "processed": { - "type": "boolean" + { + "date": "2015-10-25", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "open": { - "type": "boolean" + { + "date": "2015-10-26", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "click": { - "type": "boolean" + { + "date": "2015-10-27", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "dropped": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "url": "url", - "group_resubscribe": true, - "delivered": true, - "group_unsubscribe": true, - "spamreport": true, - "bounce": true, - "deferred": true, - "unsubscribe": true, - "processed": true, - "open": true, - "click": true, - "dropped": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Retrieve Event Webhook Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" + { + "date": "2015-10-28", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "url": { - "type": "string" + { + "date": "2015-10-29", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "group_resubscribe": { - "type": "boolean" + { + "date": "2015-10-30", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "delivered": { - "type": "boolean" + { + "date": "2015-10-31", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "group_unsubscribe": { - "type": "boolean" + { + "date": "2015-11-01", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "spam_report": { - "type": "boolean" + { + "date": "2015-11-02", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "bounce": { - "type": "boolean" + { + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "deferred": { - "type": "boolean" + { + "date": "2015-11-04", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-05", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "unsubscribe": { - "type": "boolean" + { + "date": "2015-11-06", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "processed": { - "type": "boolean" + { + "date": "2015-11-07", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "open": { - "type": "boolean" + { + "date": "2015-11-08", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "click": { - "type": "boolean" + { + "date": "2015-11-09", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "dropped": { - "type": "boolean" + { + "date": "2015-11-10", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] } - } + ] }, - "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 - } + "schema": { + "items": { + "properties": { + "date": { + "description": "The date that the stats were collected.", + "type": "string" + }, + "stats": { + "description": "The Parse Webhook usage statistics.", + "items": { + "properties": { + "metrics": { + "properties": { + "received": { + "description": "The number of emails received and parsed by the Parse Webhook.", + "type": "number" + } + }, + "required": [ + "received" + ], + "type": "object" + } + }, + "type": "object" + }, + "type": "array" + } + }, + "required": [ + "date", + "stats" + ], + "type": "object" + }, + "type": "array" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } + ], + "summary": "" + }, + "parameters": [] }, - "/user/webhooks/event/test": { - "parameters": [], - "post": { - "description": "", - "operationId": "Test Event Notification Settings ", + "/whitelabel/domains": { + "get": { "consumes": [ "application/json" ], - "produces": [], + "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": "List all domain whitelabels.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "url": { - "type": "string" - } - } - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ + "description": "Number of domains to return.", + "in": "query", + "name": "limit", + "type": "integer" + }, { - "Authorization": [] + "description": "Paging offset.", + "in": "query", + "name": "offset", + "type": "integer" + }, + { + "description": "Exclude subuser domains from the result.", + "in": "query", + "name": "exclude_subusers", + "type": "boolean" + }, + { + "description": "The username associated with a whitelabel.", + "in": "query", + "name": "username", + "type": "string" + }, + { + "description": "Search for domain whitelabels that match the given domain.", + "in": "query", + "name": "domain", + "type": "string" } - ] - } - }, - "/user/webhooks/parse/settings": { - "parameters": [], - "get": { - "description": "", - "operationId": "Retrieve Parse API settings", - "consumes": [ - "application/json" ], "produces": [ "application/json" ], - "parameters": [], "responses": { "200": { "description": "", + "examples": { + "application/json": [ + { + "automatic_security": true, + "custom_spf": true, + "default": true, + "dns": { + "dkim1": { + "data": "s1._domainkey.u7.wl.sendgrid.net", + "host": "s1._domainkey.example.com", + "type": "cname", + "valid": true + }, + "dkim2": { + "data": "s2._domainkey.u7.wl.sendgrid.net", + "host": "s2._domainkey.example.com", + "type": "cname", + "valid": true + }, + "mail_cname": { + "data": "u7.wl.sendgrid.net", + "host": "mail.example.com", + "type": "cname", + "valid": true + }, + "spf": { + "data": "v=spf1 include:u7.wl.sendgrid.net -all", + "host": "example.com", + "type": "txt", + "valid": true + } + }, + "domain": "example.com", + "id": 1, + "ips": [ + "192.168.1.1", + "192.168.1.2" + ], + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "john@example.com", + "valid": true + }, + { + "automatic_security": true, + "custom_spf": false, + "default": true, + "dns": { + "dkim": { + "data": "k=rsa; t=s; p=publicKey", + "host": "example2.com", + "type": "txt", + "valid": false + }, + "domain_spf": { + "data": "v=spf1 include:news.example2.com -all", + "host": "example2.com", + "type": "txt", + "valid": false + }, + "mail_server": { + "data": "sendgrid.net", + "host": "news.example2.com", + "type": "mx", + "valid": false + }, + "subdomain_spf": { + "data": "v=spf1 include:sendgrid.net ~all", + "host": "news.example2.com", + "type": "txt", + "valid": false + } + }, + "domain": "example2.com", + "id": 2, + "ips": [], + "legacy": false, + "subdomain": "news", + "user_id": 8, + "username": "jane@example2.com", + "valid": false + } + ] + }, "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", + "items": { + "properties": { + "automatic_security": { + "description": "Indicates if this whitelabel uses automated security.", + "type": "boolean" + }, + "custom_spf": { + "description": "Indicates if this whitelabel has custom SPF.", + "type": "boolean" + }, + "default": { + "description": "Indicates if this whitelabel has been set as the default whitelabel.", + "type": "boolean" + }, + "dns": { + "description": "The DNS records for this whitelabel that are used for authenticating the sending domain.", "properties": { - "hostname": { - "type": "string" - }, - "url": { - "type": "string" + "dkim": { + "description": "The DNS record used when creating the DKIM signature.", + "properties": { + "data": { + "description": "The DNS record.", + "type": "string" + }, + "host": { + "description": "The domain that these DNS records will be applied to.", + "format": "hostname", + "type": "string" + }, + "type": { + "description": "The type of DNS record.", + "enum": [ + "cname", + "mx", + "txt" + ], + "type": "string" + }, + "valid": { + "description": "Indicates if this DNS record is valid.", + "type": "boolean" + } + }, + "type": "object" }, - "spam_check": { - "type": "boolean" + "mail_server": { + "description": "Designates which mail server is responsible for accepting messages from a domain.", + "properties": { + "data": { + "description": "The mail server responsible for accepting messages.", + "type": "string" + }, + "host": { + "description": "The domain sending the messages.", + "type": "string" + }, + "type": { + "description": "The type of DNS record.", + "type": "string" + }, + "valid": { + "description": "Indicates if this is a valid DNS record with no conflicts.", + "type": "boolean" + } + }, + "type": "object" }, - "send_raw": { - "type": "boolean" + "subdomain_spf": { + "description": "The SPF record for the subdomain used to create this whitelabel.", + "properties": { + "data": { + "description": "The SPF record.", + "type": "string" + }, + "host": { + "description": "The domain that this SPF record will be used to authenticate.", + "type": "string" + }, + "type": { + "description": "The type of data in the SPF record.", + "type": "string" + }, + "valid": { + "description": "Indicates if the SPF record is valid.", + "type": "boolean" + } + }, + "type": "object" } - } - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "hostname": "example.com", - "url": "http://example.com/example", - "spam_check": false, - "send_raw": false + }, + "type": "object" + }, + "domain": { + "description": "The domain that this whitelabel was created for.", + "type": "string" + }, + "id": { + "description": "The ID of the domain whitelabel.", + "type": "number" + }, + "ips": { + "description": "The IPs that will be included in the custom SPF record.", + "items": { + "type": "string" + }, + "type": "array" + }, + "legacy": { + "description": "Indicates if this is whitelabel was created with the legacy whitelabel tool.", + "type": "boolean" + }, + "subdomain": { + "description": "The subdomain created for this domain whitelabel.", + "type": "string" + }, + "user_id": { + "description": "The ID of the user that this whitelabel will be associated with.", + "type": "number" + }, + "username": { + "description": "The username that this whitelabel is associated with.", + "type": "string" + }, + "valid": { + "description": "Indicates if this is a valid whitelabel or not.", + "type": "boolean" } - ] - } + }, + "required": [ + "id", + "user_id", + "subdomain", + "domain", + "username", + "ips", + "custom_spf", + "default", + "legacy", + "automatic_security", + "valid", + "dns" + ], + "type": "object" + }, + "type": "array" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - }, - "/whitelabel/ips/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "integer" - } - ], + ], + "summary": "" + }, + "parameters": [], "post": { - "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": "Validate an IP whitelabel", "consumes": [ "application/json" ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", + "description": "**This endpoint allows you to create a whitelabel for one of your domains.**\n\nIf you are creating a domain whitelabel that you would like a subuser to use, you have two options:\n1. 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.\n2. 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.\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": "Create a domain whitelabel.", + "parameters": [ + { + "in": "body", + "name": "body", "schema": { - "type": "object", "properties": { - "id": { - "type": "integer", - "description": "The id of the IP whitelabel." + "automatic_security": { + "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.", + "type": "boolean" }, - "valid": { - "type": "boolean", - "description": "Indicates if the IP whitelabel is valid.", - "enum": [ - true, - false - ] + "custom_spf": { + "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.", + "type": "boolean" }, - "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.", + "default": { + "description": "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain.", + "type": "boolean" + }, + "domain": { + "description": "Domain being whitelabeled.", + "type": "string" + }, + "ips": { + "description": "The IP addresses that will be included in the custom SPF record for this whitelabel.", "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message describing why the IP whitelabel could not be validated." - } - }, - "required": [ - "message" - ] - } + "type": "string" + }, + "type": "array" + }, + "subdomain": { + "description": "The subdomain to use for this domain whitelabel.", + "type": "string" + }, + "username": { + "description": "The username that this whitelabel will be associated with.", + "type": "string" } }, "required": [ - "errors" - ] - }, + "domain", + "subdomain" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", "examples": { "application/json": { - "errors": [ - { - "message": "internal error getting rDNS" + "automatic_security": true, + "custom_spf": false, + "default": true, + "dns": { + "dkim1": { + "data": "s1.domainkey.u1446226.wl.sendgrid.net", + "host": "s1._domainkey.example.com", + "type": "cname", + "valid": false + }, + "dkim2": { + "data": "s2.domainkey.u1446226.wl.sendgrid.net", + "host": "s2._domainkey.example.com", + "type": "cname", + "valid": false + }, + "mail_cname": { + "data": "u1446226.wl.sendgrid.net", + "host": "example.example.com", + "type": "cname", + "valid": false } - ] + }, + "domain": "example.com", + "id": 302183, + "ips": [], + "legacy": false, + "subdomain": "example", + "user_id": 1446226, + "username": "mbernier", + "valid": false } + }, + "schema": { + "$ref": "#/definitions/whitelabel::domain" } } }, - "summary": "", "security": [ { "Authorization": [] } - ] - } - } - }, - "definitions": { - "contacts": { - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": {}, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "zip": { - "type": "string" - } + ], + "summary": "When creating a whitelabel for a subuser, there are two options available:\n Use the \"username\" parameter. This allows" } }, - "subuser": { - "title": "List all Subusers for a parent response", - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not the user is enabled or disabled." - }, - "id": { - "type": "number", - "description": "The ID of this subuser." - }, - "username": { - "type": "string", - "description": "The name by which this subuser will be referred." + "/whitelabel/domains/default": { + "get": { + "consumes": [ + "application/json" + ], + "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 the default domain whitelabel.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/whitelabel:domain_spf" + } + } }, - "email": { - "type": "string", - "description": "The email address to contact this subuser.", - "format": "email" - } + "security": [ + { + "Authorization": [] + } + ], + "summary": "" }, - "required": [ - "disabled", - "id", - "username", - "email" - ] + "parameters": [] }, - "contactdb_segments_conditions": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "value": { - "type": "string" - }, - "operator": { - "type": "string", - "enum": [ - "eq", - "ne", - "lt", - "gt", - "contains" - ] + "/whitelabel/domains/subuser": { + "delete": { + "consumes": [ + "application/json" + ], + "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": "Disassociate a domain whitelabel from a given user.", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" + } }, - "and_or": { - "type": "string", - "enum": [ - "and", - "or", - "" - ] - } + "security": [ + { + "Authorization": [] + } + ], + "summary": "Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows\nsubusers to send mail" }, - "required": [ - "field", - "value", - "operator" - ] - }, - "subuser_post": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser." - }, - "user_id": { - "type": "number", - "description": "The user ID for this subuser." - }, - "email": { - "type": "string", - "description": "The email address for this subuser.", - "format": "email" - }, - "signup_session_token": { - "type": "string" - }, - "authorization_token": { - "type": "string" - }, - "credit_allocation": { - "type": "object", - "properties": { - "type": { - "type": "string" + "get": { + "consumes": [ + "application/json" + ], + "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": "List the domain whitelabel associated with the given user.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "automatic_security": false, + "custom_spf": true, + "default": false, + "dns": { + "dkim": { + "data": "k=rsa; t=s; p=publicKey", + "host": "s1._domainkey.example.com", + "type": "txt", + "valid": false + }, + "domain_spf": { + "data": "v=spf1 include:mail.example.com -all", + "host": "example.com", + "type": "txt", + "valid": false + }, + "mail_server": { + "data": "sendgrid.net", + "host": "mail.example.com", + "type": "mx", + "valid": false + }, + "subdomain_spf": { + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "host": "mail.example.com", + "type": "txt", + "valid": false + } + }, + "domain": "example.com", + "id": 1, + "ips": [], + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "mail@example.com", + "valid": false + } + }, + "schema": { + "$ref": "#/definitions/whitelabel:domain_spf" } } - } - }, - "required": [ - "username", - "user_id", - "email" - ] - }, - "contactdb_segments": { - "title": "Create a Segment request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of this segment." }, - "list_id": { - "type": "integer", - "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." - }, - "conditions": { - "type": "array", - "description": "The conditions for a recipient to be included in this segment.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" + "security": [ + { + "Authorization": [] } - }, - "recipient_count": { - "type": "number", - "description": "The count of recipients in this list. This is not included on creation of segments." - } + ], + "summary": "" }, - "required": [ - "name", - "conditions" - ] + "parameters": [] }, - "campaign_request": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." - }, - "subject": { - "type": [ - "string", - "null" - ], - "description": "The subject of your campaign that your recipients will see." - }, - "sender_id": { - "type": [ - "null", - "integer" - ], - "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails." - }, - "list_ids": { - "type": [ - "array", - "null" - ], - "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", - "items": { - "type": "integer" + "/whitelabel/domains/{domain_id}": { + "delete": { + "consumes": [ + "application/json" + ], + "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 a domain whitelabel.", + "parameters": [], + "produces": [], + "responses": { + "204": { + "description": "" } }, - "segment_ids": { - "type": [ - "array", - "null" - ], - "description": "The segment IDs that you are sending this list to. You can have both segment IDs and list IDs.", - "items": { - "type": "integer" + "security": [ + { + "Authorization": [] } - }, - "categories": { - "type": [ - "array", - "null" - ], - "description": "The categories you would like associated to this campaign.", - "items": { - "type": "string" + ], + "summary": "" + }, + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve a domain whitelabel.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/whitelabel::domain" + } } }, - "suppression_group_id": { - "type": [ - "null", - "integer" - ], - "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type." - }, - "custom_unsubscribe_url": { - "type": [ - "string", - "null" - ], - "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups." - }, - "ip_pool": { - "type": [ - "string", - "null" - ], - "description": "The pool of IPs that you would like to send this email from." - }, - "html_content": { - "type": [ - "string", - "null" - ], - "description": "The HTML of your marketing email." - }, - "plain_content": { - "type": [ - "string", - "null" - ], - "description": "The plain text content of your emails." - } + "security": [ + { + "Authorization": [] + } + ], + "summary": "" }, - "required": [ - "title" - ] - }, - "contactdb_recipient_response": { - "type": "object", - "properties": { - "error_count": { - "type": "number", - "default": "0", - "description": "The number of errors found while adding recipients." - }, - "error_indices": { - "type": "array", - "default": "[]", - "description": "The indices of the recipient(s) sent that caused the error. ", - "items": { - "type": "number" + "parameters": [ + { + "description": "The id of the domain whitelabel.", + "in": "path", + "name": "id", + "required": true, + "type": "number" + } + ], + "patch": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to update the settings for 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": "Update a domain whitelabel.", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "custom_spf": { + "default": "false", + "description": "Indicates whether to generate a custom SPF record for manual security.", + "type": "boolean" + }, + "default": { + "default": "false", + "description": "Indicates whether this domain whitelabel should be considered the default.", + "type": "boolean" + } + }, + "type": "object" + } } - }, - "new_count": { - "type": "number", - "default": "0", - "description": "The count of new recipients added to the contactdb." - }, - "persisted_recipients": { - "type": "array", - "default": "[]", - "description": "The recipient IDs of the recipients that already existed from this request.", - "items": { - "type": "string" + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "schema": { + "properties": { + "custom_spf false": { + "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", + "type": "boolean" + }, + "default false": { + "description": "Inidcates whether this domain whitelabel should be considered the default. Defaults to false.", + "type": "boolean" + } + }, + "title": "Update a Domain response", + "type": "object" + } } }, - "updated_count": { - "type": "number", - "default": "0", - "description": "The recipients who were updated from this request." - }, - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_indices": { - "type": "array", - "items": { - "type": "number" + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/whitelabel/domains/{domain_id}/subuser": { + "parameters": [ + { + "in": "path", + "name": "domain_id", + "required": true, + "type": "string" + } + ], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to associate a specific domain whitelabel with 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 | Description |\n|---|---|---|\n| domain_id | integer | ID of the domain whitelabel to associate with the subuser. |", + "operationId": "Associate a domain whitelabel with a given user.", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "username": { + "description": "Username to associate with the domain whitelabel.", + "type": "string" } + }, + "required": [ + "username" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", + "examples": { + "application/json": { + "automatic_security": false, + "custom_spf": true, + "default": false, + "dns": { + "dkim": { + "data": "k=rsa; t=s; p=publicKey", + "host": "s1._domainkey.example.com", + "type": "txt", + "valid": false + }, + "domain_spf": { + "data": "v=spf1 include:mail.example.com -all", + "host": "example.com", + "type": "txt", + "valid": false + }, + "mail_server": { + "data": "sendgrid.net", + "host": "mail.example.com", + "type": "mx", + "valid": false + }, + "subdomain_spf": { + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "host": "mail.example.com", + "type": "txt", + "valid": false + } + }, + "domain": "example.com", + "id": 1, + "ips": [], + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "mail@example.com", + "valid": false } + }, + "schema": { + "$ref": "#/definitions/whitelabel:domain_spf" } } - } - }, - "required": [ - "error_count", - "new_count", - "persisted_recipients", - "updated_count" - ] - }, - "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" - ] + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } }, - "api_key_name_id_scopes": { - "allOf": [ + "/whitelabel/domains/{id}/ips": { + "parameters": [ { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permissions this API Key has access to.", - "items": { - "type": "string" + "in": "path", + "name": "id", + "required": true, + "type": "string" + } + ], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to add an IP address to 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)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain to which you are adding an IP |", + "operationId": "Add an IP to a domain whitelabel.", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "ip": { + "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF.", + "type": "string" + } + }, + "required": [ + "ip" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "automatic_security": false, + "custom_spf": true, + "default": false, + "dns": { + "dkim": { + "data": "k=rsa; t=s; p=publicKey", + "host": "s1._domainkey.example.com", + "type": "txt", + "valid": false + }, + "domain_spf": { + "data": "v=spf1 include:mail.example.com -all", + "host": "example.com", + "type": "txt", + "valid": false + }, + "mail_server": { + "data": "sendgrid.net", + "host": "mail.example.com", + "type": "mx", + "valid": false + }, + "subdomain_spf": { + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "host": "mail.example.com", + "type": "txt", + "valid": false + } + }, + "domain": "example.com", + "id": 1, + "ips": [], + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "john@example.com", + "valid": false } + }, + "schema": { + "$ref": "#/definitions/whitelabel:domain_spf" } } }, - { - "$ref": "#/definitions/api_key_name_id" - } - ] + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } }, - "credentials": { - "type": "object", - "properties": { - "permissions": { - "type": "object", - "properties": { - "api": { - "type": "string" - }, - "mail": { - "type": "string" + "/whitelabel/domains/{id}/ips/{ip}": { + "delete": { + "consumes": [ + "application/json" + ], + "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": "Remove an IP from a domain whitelabel.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "automatic_security": false, + "custom_spf": true, + "default": false, + "dns": { + "dkim": { + "data": "k=rsa; t=s; p=publicKey", + "host": "s1._domainkey.example.com", + "type": "txt", + "valid": false + }, + "domain_spf": { + "data": "v=spf1 include:mail.example.com -all", + "host": "example.com", + "type": "txt", + "valid": false + }, + "mail_server": { + "data": "sendgrid.net", + "host": "mail.example.com", + "type": "mx", + "valid": false + }, + "subdomain_spf": { + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "host": "mail.example.com", + "type": "txt", + "valid": false + } + }, + "domain": "example.com", + "id": 1, + "ips": [], + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "mail@example.com", + "valid": false + } }, - "web": { - "type": "string" + "schema": { + "$ref": "#/definitions/whitelabel:domain_spf" } } }, - "username": { - "type": "string" - } - } - }, - "partner_settings_new_relic": { - "type": "object", - "properties": { - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this setting is enabled. " - }, - "license_key": { - "type": "string", - "description": "The license key provided with your New Relic account." - } - }, - "required": [ - "enabled", - "license_key" - ] - }, - "suppression_group_unsubscribes": { - "type": "object", - "allOf": [ - { - "$ref": "#/definitions/suppression_group" - }, - { - "type": "object", - "required": [ - "unsubscribes" - ], - "properties": { - "unsubscribes": { - "type": "integer", - "description": "The unsubscribes associated with this group." - } + "security": [ + { + "Authorization": [] } - } - ] - }, - "mail_settings_forward_bounce": { - "type": "object", - "properties": { - "email": { - "type": [ - "string", - "null" - ] - }, - "enabled": { - "type": "boolean" - } - } - }, - "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." - } - } - }, - "monitor": { - "title": "Create monitor settings request", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address to send emails at the frequency specified for monitoring.", - "format": "email" - }, - "frequency": { - "type": "number", - "description": "The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. " - } + ], + "summary": "" }, - "required": [ - "email", - "frequency" - ] - }, - "global:id": { - "type": "integer" - }, - "mail_settings_template": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - } - }, - "mail_settings_spam_check": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "max_score": { - "type": "integer" - }, - "url": { - "type": "string" - } - } - }, - "mail_settings_forward_spam": { - "type": "object", - "properties": { - "email": { - "type": [ - "string", - "null" - ] - }, - "enabled": { - "type": "boolean" - } - } - }, - "mail_settings::patch": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "email": { + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, "type": "string" - } - } - }, - "mail_settings_bounce_purge": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "soft_bounces": { - "type": [ - "integer", - "null" - ] }, - "hard_bounces": { - "type": [ - "integer", - "null" - ] - } - } - }, - "mail_settings_bcc": { - "type": "object", - "properties": { - "email": { + { + "in": "path", + "name": "ip", + "required": true, "type": "string" - }, - "enabled": { - "type": "boolean" - } - } - }, - "mail_settings_address_whitelabel": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "list": { - "type": "array", - "items": { - "type": "string" - } } - } - }, - "global:empty_request": { - "type": "null" - }, - "mail_batch_id": { - "type": "object", - "properties": { - "batch_id": { - "type": "string", - "pattern": "^[a-zA-Z0-9\\-\\_]" - } - }, - "required": [ - "batch_id" ] }, - "campaign_response": { - "allOf": [ - { - "$ref": "#/definitions/campaign_request" - }, + "/whitelabel/domains/{id}/validate": { + "parameters": [ { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status of your campaign." + "in": "path", + "name": "id", + "required": true, + "type": "string" + } + ], + "post": { + "consumes": [ + "application/json" + ], + "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": "Validate a domain whitelabel.", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "id": 1, + "valid": true, + "validation_resuts": { + "dkim1": { + "reason": null, + "valid": true + }, + "dkim2": { + "reason": null, + "valid": true + }, + "mail_cname": { + "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\".", + "valid": false + }, + "spf": { + "reason": null, + "valid": true + } + } + } }, - "id": { - "type": "integer" + "schema": { + "properties": { + "id": { + "description": "The ID of the domain whitelabel.", + "type": "integer" + }, + "valid": { + "description": "Indicates if this is a valid whitelabel.", + "type": "boolean" + }, + "validation_resuts": { + "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", + "properties": { + "dkim1": { + "description": "A DNS record for this domain whitelabel.", + "properties": { + "reason": { + "type": "null" + }, + "valid": { + "description": "Indicates if the DNS record is valid.", + "type": "boolean" + } + }, + "type": "object" + }, + "dkim2": { + "description": "A DNS record for this whitelabel.", + "properties": { + "reason": { + "type": "null" + }, + "valid": { + "description": "Indicates if the DNS record is valid.", + "type": "boolean" + } + }, + "type": "object" + }, + "mail_cname": { + "description": "The CNAME record for the domain whitelabel.", + "properties": { + "reason": { + "description": "The reason this record is invalid.", + "type": "string" + }, + "valid": { + "description": "Indicates if this DNS record is valid.", + "type": "boolean" + } + }, + "type": "object" + }, + "spf": { + "description": "The SPF record for the whitelabel.", + "properties": { + "reason": { + "type": "null" + }, + "valid": { + "description": "Indicates if the SPF record is valid.", + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "type": "object" } }, - "required": [ - "status" - ] - } - ] - }, - "contactdb_segments_with_id": { - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the segment." + "400": { + "description": "Unexpected error in API call. See HTTP response body for details.", + "schema": { + "properties": {}, + "type": "object" } }, - "required": [ - "id" - ] - }, - { - "$ref": "#/definitions/contactdb_segments" - } - ] - }, - "contactdb_custom_field_with_id_value": { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field_with_id" - }, - { - "type": "object", - "properties": { - "value": { - "type": [ - "string", - "null" - ], - "description": "The value of this recipient's custom field" + "500": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "internal error getting TXT" + } + ] + } + }, + "schema": { + "properties": { + "errors": { + "items": { + "properties": { + "message": { + "description": "A message explaining the reason for the error.", + "type": "string" + } + }, + "required": [ + "message" + ], + "type": "object" + }, + "type": "array" + } + }, + "type": "object" } } - } - ], - "title": "ContactDB Custom field schema." - }, - "contactdb_custom_field_with_id": { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field" }, - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the custom field." - } + "security": [ + { + "Authorization": [] } - } - ], - "title": "ContactDB Custom field schema with ID." - }, - "contactdb_custom_field": { - "title": "ContactDB Custom field schema.", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the field" - }, - "type": { - "type": "string", - "description": "The type of the field.", - "enum": [ - "date", - "text", - "number" - ] - } - } - }, - "contactdb_recipient_count": { - "type": "object", - "properties": { - "recipient_count": { - "type": "number", - "description": "The count of recipients." - } - }, - "required": [ - "recipient_count" - ] - }, - "mail_settings_footer": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } + ], + "summary": "" } }, - "user_scheduled_send_status": { - "allOf": [ - { - "$ref": "#/definitions/mail_batch_id" - }, - { - "type": "object", - "description": "The status of the scheduled send.", - "properties": { - "status": { - "type": "string", - "description": "The status of the scheduled send.", - "enum": [ - "cancel", - "pause" - ] - } + "/whitelabel/ips": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve all IP whitelabels", + "parameters": [ + { + "description": "The number of results to retrieve.", + "in": "query", + "name": "limit", + "type": "integer" }, - "required": [ - "status" - ] - } - ] - }, - "contactdb_list": { - "title": "ContactDB lists", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The reference ID of your list." - }, - "name": { - "type": "string", - "description": "The name of your list." + { + "description": "The point in the list of results to begin retrieving IPs from.", + "in": "query", + "name": "offset", + "type": "integer" + }, + { + "description": "The IP segment that you would like to use in a prefix search.", + "in": "query", + "name": "ip", + "type": "string" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ + { + "a_record": { + "data": "192.168.1.1", + "host": "o1.email.example.com", + "type": "a", + "valid": true + }, + "domain": "example.com", + "id": 1, + "ip": "192.168.1.1", + "legacy": false, + "rdns": "o1.email.example.com", + "subdomain": "email", + "users": [ + { + "user_id": 7, + "username": "john@example.com" + }, + { + "user_id": 8, + "username": "jane@example.com" + } + ], + "valid": true + }, + { + "a_record": { + "data": "192.168.1.2", + "host": "o2.email.example.com", + "type": "a", + "valid": true + }, + "domain": "example.com", + "id": 2, + "ip": "192.168.1.2", + "legacy": false, + "rdns": "o2.email.example.com", + "subdomain": "email", + "users": [ + { + "user_id": 7, + "username": "john@example.com" + }, + { + "user_id": 9, + "username": "jane@example2.com" + } + ], + "valid": true + } + ] + }, + "schema": { + "items": { + "$ref": "#/definitions/ip_whitelabel" + }, + "type": "array" + } + } }, - "recipient_count": { - "type": "integer", - "description": "The count of recipients currently in the list." - } + "security": [ + { + "Authorization": [] + } + ], + "summary": "" }, - "required": [ - "id", - "name", - "recipient_count" - ] - }, - "user_profile": { - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "website": { - "type": "string" - }, - "zip": { - "type": "string" - } - } - }, - "global:ErrorResponse": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": [ - "string", - "null" - ], - "description": "The field that generated the error." + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to create an IP whitelabel.**\n\nWhen creating an IP whitelable, you should use the same subdomain that you used when you created a domain 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": "Create an IP whitelabel", + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "domain": { + "description": "The root, or sending, domain that will be used to send message from the IP.", + "type": "string" + }, + "ip": { + "description": "The IP address that you want to whitelabel.", + "type": "string" + }, + "subdomain": { + "description": "The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel.", + "type": "string" + } }, - "message": { - "type": "string", - "description": "The error message." + "required": [ + "ip", + "subdomain", + "domain" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", + "examples": { + "application/json": { + "a_record": { + "data": "192.168.1.2", + "host": "o1.email.example.com", + "type": "a", + "valid": true + }, + "domain": "example.com", + "id": 123, + "ip": "192.168.1.2", + "legacy": false, + "rdns": "o1.email.example.com", + "subdomain": "email", + "users": [], + "valid": true } }, - "required": [ - "message" - ] + "schema": { + "$ref": "#/definitions/ip_whitelabel" + } } - } - } - }, - "suppression_bounce": { - "type": "object", - "properties": { - "created": { - "type": "number", - "description": "The unix timestamp for when the bounce record was created at SendGrid." - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string", - "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." }, - "status": { - "type": "string", - "description": "Enhanced SMTP bounce response" - } + "security": [ + { + "Authorization": [] + } + ], + "summary": "" } }, - "contactdb_recipient": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of this recipient." - }, - "created_at": { - "type": "number", - "description": "The time this record was created in your contactdb, in unixtime." - }, - "custom_fields": { - "type": "array", - "description": "The custom fields assigned to this recipient and their values.", - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id_value" + "/whitelabel/ips/{id}": { + "delete": { + "consumes": [ + "application/json" + ], + "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 an IP whitelabel", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "204": { + "description": "", + "schema": { + "properties": {}, + "type": "object" + } + }, + "404": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] + } + }, + "schema": { + "properties": { + "errors": { + "description": "The errors preventing the IP whitelabel from being deleted.", + "items": { + "properties": { + "message": { + "description": "A message explaining why the IP whitelabel could not be deleted.", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" } }, - "email": { - "type": "string", - "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", - "format": "email" - }, - "first_name": { - "type": [ - "string", - "null" - ], - "description": "The first name of this recipient. This is a default custom field that SendGrid provides." - }, - "last_name": { - "type": [ - "string", - "null" - ], - "description": "The last name of the recipient." - }, - "last_clicked": { - "type": [ - "number", - "null" - ], - "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." - }, - "last_emailed": { - "type": [ - "number", - "null" - ], - "description": "The last time this user was emailed by one of your campaigns, in unixtime." - }, - "last_opened": { - "type": [ - "number", - "null" + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + }, + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve an IP whitelabel", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "a_record": { + "data": "192.168.1.1", + "host": "o1.email.example.com", + "type": "a", + "valid": true + }, + "domain": "example.com", + "id": 123, + "ip": "192.168.1.1", + "legacy": false, + "rdns": "o1.email.example.com", + "subdomain": "email", + "users": [ + { + "user_id": 7, + "username": "john@example.com" + } ], - "description": "The last time this recipient opened an email from you, in unixtime." - }, - "updated_at": { - "type": "number", - "description": "The last update date for this recipient's record." + "valid": true } }, - "required": [ - "email" - ] - } - } - } - }, - "whitelabel::domain": { - "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 to use for this domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel is being created for." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel will be associated with." - }, - "ips": { - "type": "array", - "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", - "items": { - "type": "object", - "properties": {} - } - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates whether this domain whitelabel will use custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this domain whitelabel is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this domain whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel that are used to authenticate the sending domain.", - "required": [ - "mail_cname", - "dkim1", - "dkim2" - ], - "properties": { - "mail_cname": { - "type": "object", - "description": "The CNAME for your sending domain that points to sendgrid.net.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid CNAME." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this CNAME is created for.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The CNAME record." - } + "schema": { + "$ref": "#/definitions/ip_whitelabel" + } + }, + "404": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] } }, - "dkim1": { - "type": "object", - "description": "A DNS record.", - "required": [ - "valid", - "type", - "host", - "data" - ], + "schema": { "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." + "errors": { + "description": "The errors preventing the retrieval of the IP whitelabel.", + "items": { + "properties": { + "message": { + "description": "A message explaining why the IP whitelabel could not be found.", + "type": "string" + } + }, + "required": [ + "message" + ], + "type": "object" + }, + "type": "array" } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record.", + }, "required": [ - "valid", - "type", - "host", - "data" + "errors" ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } + "type": "object" } } - } + }, + "security": [ + { + "Authorization": [] + } + ], + "summary": "" }, - "required": [ - "id", - "user_id", - "subdomain", - "domain", - "username", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" + "parameters": [ + { + "description": "The id of the IP whitelabel that you would like to retrieve.", + "in": "path", + "name": "id", + "required": true, + "type": "string" + } ] }, - "whitelabel:domain_spf": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." - }, - "subdomain": { - "type": "string", - "description": "The subdomain that was used to create this whitelabel." - }, - "username": { - "type": "string", - "description": "The username of the account that this whitelabel is associated with." - }, - "user_id": { - "type": "integer", - "description": "The user_id of the account that this whitelabel is associated with." - }, - "ips": { - "type": "array", - "description": "The IP addresses that are included in the SPF record for this whitelabel.", - "items": {} - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel uses custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using 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." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel.", - "required": [ - "mail_server", - "subdomain_spf", - "domain_spf", - "dkim" - ], - "properties": { - "mail_server": { - "type": "object", - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain sending the messages." - }, - "type": { - "type": "string", - "description": "They type of DNS record." - }, - "data": { - "type": "string", - "description": "The mail server responsible for accepting messages from the sending domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - } - } - }, - "subdomain_spf": { - "type": "object", - "description": "The SPF record for the subdomain used to create this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid SPF record." + "/whitelabel/ips/{id}/validate": { + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "type": "integer" + } + ], + "post": { + "consumes": [ + "application/json" + ], + "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": "Validate an IP whitelabel", + "parameters": [], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": { + "id": 1, + "valid": true, + "validation_results": { + "a_record": { + "reason": null, + "valid": true + } } } }, - "domain_spf": { - "type": "object", - "description": "The SPF record for the root domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], + "schema": { "properties": { - "host": { - "type": "string", - "description": "The root domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." + "id": { + "description": "The id of the IP whitelabel.", + "type": "integer" }, "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." + "description": "Indicates if the IP whitelabel is valid.", + "enum": [ + true, + false + ], + "type": "boolean" + }, + "validation_results": { + "description": "The specific results of the validation.", + "properties": { + "a_record": { + "properties": { + "reason": { + "description": "The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated.", + "type": [ + "null", + "string" + ] + }, + "valid": { + "description": "Indicates if the IP whitelabel could be validated.", + "enum": [ + true, + false + ], + "type": "boolean" + } + }, + "required": [ + "valid", + "reason" + ], + "type": "object" + } + }, + "type": "object" } + }, + "required": [ + "id", + "valid", + "validation_results" + ], + "type": "object" + } + }, + "404": { + "description": "Unexpected error in API call. See HTTP response body for details.", + "examples": { + "application/json": { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] } }, - "dkim": { - "type": "object", - "description": "The DKIM record for messages sent using this whitelabel.", + "schema": { + "properties": { + "errors": { + "description": "The error messages for the failed validation.", + "items": { + "properties": { + "message": { + "description": "A message describing why the IP could not be validated.", + "type": "string" + } + }, + "required": [ + "message" + ], + "type": "object" + }, + "type": "array" + } + }, "required": [ - "host", - "type", - "data", - "valid" + "errors" ], + "type": "object" + } + }, + "500": { + "description": "", + "examples": { + "application/json": { + "errors": [ + { + "message": "internal error getting rDNS" + } + ] + } + }, + "schema": { "properties": { - "host": { - "type": "string", - "description": "The DNS labels for the DKIM signature." - }, - "type": { - "type": "string", - "description": "The type of data in the DKIM record." - }, - "data": { - "type": "string", - "description": "The DKIM record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the DKIM record is valid." + "errors": { + "description": "The error messages for the failed validation.", + "items": { + "properties": { + "message": { + "description": "A message describing why the IP whitelabel could not be validated.", + "type": "string" + } + }, + "required": [ + "message" + ], + "type": "object" + }, + "type": "array" } - } + }, + "required": [ + "errors" + ], + "type": "object" } } - } - }, - "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - }, - "transactional_template": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the transactional template." - }, - "name": { - "type": "string", - "description": "The name for the transactional template.", - "maxLength": 100 }, - "versions": { - "type": "array", - "description": "The different versions of this transactional template.", - "items": { - "$ref": "#/definitions/transactional_template_version" + "security": [ + { + "Authorization": [] } - } - }, - "required": [ - "id", - "name" - ] - }, - "suppression_group": { - "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": "A description of the suppression group.", - "maxLength": 100 - }, - "last_email_sent_at": { - "type": "null" - }, - "is_default": { - "type": "boolean", - "default": "false", - "description": "Indicates if this is the default suppression group." - } - }, - "required": [ - "id", - "name", - "description" - ] + ], + "summary": "" + } }, - "advanced_stats_country": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "opens", - "unique_clicks", - "unique_opens" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." + "/whitelabel/links": { + "get": { + "consumes": [ + "application/json" + ], + "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": "Retrieve all link whitelabels", + "parameters": [ + { + "description": "Limits the number of results returned per page.", + "in": "query", + "name": "limit", + "type": "integer" + } + ], + "produces": [ + "application/json" + ], + "responses": { + "200": { + "description": "", + "examples": { + "application/json": [ + { + "default": true, + "dns": { + "domain_cname": { + "data": "sendgrid.net", + "host": "mail.example.com", + "type": "cname", + "valid": true + }, + "owner_cname": { + "data": "sendgrid.net", + "host": "7.example.com", + "type": "cname", + "valid": true + } }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." + "domain": "example.com", + "id": 1, + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "john@example.com", + "valid": true + }, + { + "default": false, + "dns": { + "domain_cname": { + "data": "sendgrid.net", + "host": "news.example2.com", + "type": "cname", + "valid": true + }, + "owner_cname": { + "data": "sendgrid.net", + "host": "8.example2.com", + "type": "cname", + "valid": false + } }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } + "domain": "example2.com", + "id": 2, + "legacy": false, + "subdomain": "news", + "user_id": 8, + "username": "john@example.com", + "valid": false } - } + ] }, - "required": [ - "type", - "name", - "metrics" - ] + "schema": { + "items": { + "$ref": "#/definitions/link_whitelabel" + }, + "type": "array" + } } - } - }, - "required": [ - "date", - "stats" - ] - }, - "advanced_stats_opens": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "opens", - "unique_opens" - ], - "properties": { - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] + "security": [ + { + "Authorization": [] } - } + ], + "summary": "" }, - "required": [ - "date", - "stats" - ] - }, - "advanced_stats_clicks": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." + "parameters": [], + "post": { + "consumes": [ + "application/json" + ], + "description": "**This endpoint allows you to create a new 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": "Create a Link Whitelabel", + "parameters": [ + { + "description": "Number of domains to return.", + "in": "query", + "name": "limit", + "type": "integer" + }, + { + "description": "Paging offset.", + "in": "query", + "name": "offset", + "type": "integer" + }, + { + "in": "body", + "name": "body", + "schema": { + "properties": { + "default": { + "description": "Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.", + "enum": [ + true, + false + ], + "type": "boolean" + }, + "domain": { + "description": "The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address.", + "type": "string" + }, + "subdomain": { + "description": "The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel.", + "type": "string" + } }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "unique_clicks" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." + "required": [ + "domain", + "subdomain" + ], + "type": "object" + } + } + ], + "produces": [ + "application/json" + ], + "responses": { + "201": { + "description": "", + "examples": { + "application/json": { + "default": false, + "dns": { + "domain_cname": { + "data": "sendgrid.net", + "host": "mail.example.com", + "type": "cname", + "valid": true }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." + "owner_cname": { + "data": "sendgrid.net", + "host": "7.example.com", + "type": "cname", + "valid": true } - } + }, + "domain": "example.com", + "id": 1, + "legacy": false, + "subdomain": "mail", + "user_id": 7, + "username": "john@example.com", + "valid": true } }, - "required": [ - "type", - "name", - "metrics" - ] + "schema": { + "$ref": "#/definitions/link_whitelabel" + } } - } - }, - "required": [ - "date", - "stats" - ] - }, - "advanced_stats_mailbox_provider": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "opens", - "unique_clicks", - "unique_opens", - "blocks", - "bounces", - "deferred", - "delivered", - "drops", - "spam_reports" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "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." - }, - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "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." - }, - "drops": { - "type": "integer", - "description": "The number of emails that were not delivered due to the recipient email address being on a suppression list." + "security": [ + { + "Authorization": [] + } + ], + "summary": "" + } + }, + "/whitelabel/links/default": { + "get": { + "consumes": [ + "application/json" + ], + "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:\nCheck out our spring line!
", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [ - 110, - 124 - ], - "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" + "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 }, - { - "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" - } - ] - } - }, - "schema": { - "properties": { - "result": { - "_isOpen": true, - "items": { - "$ref": "#/definitions/campaign_response" + "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 }, - "type": "array" + "dkim": { + "host": "s1._domainkey.example.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false + } } - }, - "type": "object" + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Returns campaigns in reverse order they were created (newest first)\nReturns an empty array if no campaigns exist" + ] }, - "parameters": [], + "delete": { + "description": "**This endpoint allows you to disassociate a specific whitelabel from a subuser.**\n\nA 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.\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": "Disassociate a domain whitelabel from a given user.", + "consumes": [ + "application/json" + ], + "produces": [], + "parameters": [], + "responses": { + "204": { + "description": "" + } + }, + "summary": "Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows\nsubusers to send mail", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/whitelabel/domains/{id}/ips": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], "post": { + "description": "**This endpoint allows you to add an IP address to a domain whitelabel.**\n\nA 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.\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 to which you are adding an IP |", + "operationId": "Add an IP to a domain whitelabel.", "consumes": [ "application/json" ], - "description": "Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\n\nNote: 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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Create a Campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { - "$ref": "#/definitions/campaign_request" + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." + } + }, + "required": [ + "ip" + ] } } ], - "produces": [ - "application/json" - ], "responses": { - "201": { + "200": { "description": "", - "examples": { - "application/json": { - "categories": [ - "spring line" - ], - "custom_unsubscribe_url": "", - "html_content": "Check out our spring line!
", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [ - 110, - 124 - ], - "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" - } - }, "schema": { - "$ref": "#/definitions/campaign_response" - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"You've reached your limit of 250 campaigns. Please delete one or more and try again.\"", + "$ref": "#/definitions/whitelabel:domain_spf" + }, "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" + "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 }, - { - "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." + "subdomain_spf": { + "host": "mail.example.com", + "type": "txt", + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "valid": false }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." + "domain_spf": { + "host": "example.com", + "type": "txt", + "data": "v=spf1 include:mail.example.com -all", + "valid": false }, - { - "field": null, - "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + "dkim": { + "host": "s1._domainkey.example.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false } - ] + } } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "schema": { - "properties": {}, - "type": "object" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "{% info %}\nA campaign requires a title to be created.\nIn order to send or schedule the campaign, you will be required to" + ] } }, - "/campaigns/{campaign_id}": { - "delete": { + "/whitelabel/links/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The id of the link whitelabel you want to retrieve.", + "required": true, + "type": "integer" + } + ], + "get": { + "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": "Retrieve a Link Whitelabel", "consumes": [ "application/json" ], - "description": "For more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Delete a Campaign", - "parameters": [ - { - "description": "The ID of the campaign to delete.", - "in": "query", - "name": "campaign_id", - "required": true, - "type": "string" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "null" - } - }, - "401": { - "description": "", + "$ref": "#/definitions/link_whitelabel" + }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "properties": {}, - "type": "object" + "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" + } + } + } } - }, - "404": { - "description": "\"\": \"not found\"" } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "get": { + "patch": { + "description": "**This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.**\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": "Update a Link Whitelabel", "consumes": [ "application/json" ], - "description": "This is a place for notes and extra information about this endpoint. It is written\nin Markdown - more info in the [documentation](/docs/designer#markdown).\n\nThere are several special markdown helpers that automatically build tables\nand html off of your endpoint definition. You can find some examples in this content.\n\nClick the \"Open Editor\" button above to start editing this content.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Get a single campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "description": "The id of the campaign to retrieve.", - "in": "query", - "name": "campaign_id", - "required": true, - "type": "number" + "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 + ] + } + } + } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "categories": [ - "spring line" - ], - "custom_unsubscribe_url": "", - "html_content": "Check out our spring line!
", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [ - 110, - 124 - ], - "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" - } - }, "schema": { - "$ref": "#/definitions/campaign_response" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "$ref": "#/definitions/link_whitelabel" }, - "schema": { - "properties": {}, - "type": "object" - } - }, - "404": { - "description": "\"\": \"not found\"", "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "not found" + "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" } - ] + } } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, + "delete": { + "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 a Link Whitelabel", + "consumes": [ + "application/json" + ], + "produces": [], + "parameters": [], + "responses": { + "204": { + "description": "" + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/whitelabel/domains/{domain_id}": { "parameters": [ { + "name": "id", "in": "path", - "name": "campaign_id", + "description": "The id of the domain whitelabel.", "required": true, - "type": "string" + "type": "number" } ], "patch": { + "description": "**This endpoint allows you to update the settings for a domain whitelabel.**\n\nA 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.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", + "operationId": "Update a domain whitelabel.", "consumes": [ "application/json" ], - "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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Update a Campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", - "name": "campaign_id", - "type": "string" - }, - { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "categories": { - "description": "The categories you want to tag on this campaign.", - "items": { - "type": "string" - }, - "type": "array" - }, - "html_content": { - "description": "The HTML content of this campaign.", - "type": "string" - }, - "plain_content": { - "description": "The plain content of this campaign.", - "type": "string" + "default": { + "type": "boolean", + "default": "false", + "description": "Indicates whether this domain whitelabel should be considered the default." }, - "subject": { - "description": "The subject line for your campaign.", - "type": "string" + "custom_spf": { + "type": "boolean", + "default": "false", + "description": "Indicates whether to generate a custom SPF record for manual security." + } + } + } + } + ], + "responses": { + "200": { + "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" }, - "title": { - "description": "The title of the campaign.", - "type": "string" + "custom_spf false": { + "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", + "type": "boolean" } - }, - "required": [ - "title", - "subject", - "categories", - "html_content", - "plain_content" - ], - "title": "Update a Campaign request", - "type": "object" + } } } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "**This endpoint allows you to retrieve a specific domain whitelabel.**\n\nA 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.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", + "operationId": "Retrieve a domain whitelabel.", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "categories": [ - "summer line" - ], - "custom_unsubscribe_url": "", - "html_content": "Check out our summer line!
", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [ - 110, - 124 - ], - "plain_content": "Check out our summer line!", - "segment_ids": [ - 110 - ], - "sender_id": 124451, - "status": "Draft", - "subject": "New Products for Summer!", - "suppression_group_id": 42, - "title": "May Newsletter" - } - }, "schema": { - "properties": { - "categories": { - "items": { - "type": "string" - }, - "type": "array" - }, - "custom_unsubscribe_url": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "id": { - "format": "int64", - "type": "integer" - }, - "ip_pool": { - "type": "string" - }, - "list_ids": { - "items": { - "format": "int64", - "type": "integer" - }, - "type": "array" - }, - "plain_content": { - "type": "string" - }, - "segment_ids": { - "items": { - "format": "int64", - "type": "integer" - }, - "type": "array" - }, - "sender_id": { - "format": "int64", - "type": "integer" - }, - "status": { - "type": "string" - }, - "subject": { - "type": "string" - }, - "suppression_group_id": { - "format": "int64", - "type": "integer" - }, - "title": { - "type": "string" - } - }, - "required": [ - "id", - "title", - "subject", - "sender_id", - "list_ids", - "segment_ids", - "categories", - "suppression_group_id", - "custom_unsubscribe_url", - "ip_pool", - "html_content", - "plain_content", - "status" - ], - "title": "Update a Campaign response", - "type": "object" + "$ref": "#/definitions/whitelabel::domain" + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "description": "**This endpoint allows you to delete a domain whitelabel.**\n\nA 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.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", + "operationId": "Delete a domain whitelabel.", + "consumes": [ + "application/json" + ], + "produces": [], + "parameters": [], + "responses": { + "204": { + "description": "" + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists": { + "parameters": [], + "delete": { + "description": "Delete multiple lists.\n\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 Multiple lists", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" } }, "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", + "description": "\"id\" : \"Returned if all list ids are not valid\"", + "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." + "message": "list id was invalid" } ] } @@ -3101,428 +2420,351 @@ }, "401": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - }, - "403": { - "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "You may only update a campaign when it is in draft mode." - } - ] - } }, - "schema": { - "properties": {}, - "type": "object" - } - }, - "404": { - "description": "\"\": \"not found\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "not found" + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - } - }, - "/campaigns/{campaign_id}/schedules": { - "delete": { + ] + }, + "post": { + "description": "Create a list for your 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": "Create a List", "consumes": [ "application/json" ], - "description": "A 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": "Unschedule a Scheduled Campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", - "name": "campaign_id", - "type": "string" + "name": "body", + "in": "body", + "schema": { + "title": "Create a List request", + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + } } ], - "produces": [ - "application/json" - ], "responses": { - "204": { + "201": { "description": "", "schema": { - "type": "null" + "$ref": "#/definitions/contactdb_list" + }, + "examples": { + "application/json": { + "id": 1, + "name": "your list name", + "recipient_count": 0 + } } }, - "403": { - "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"This campaign is already Canceled.\"", + "400": { + "description": "\"name\" : \"Returned if list name is a duplicate of an existing list or segment\"\n\"name\" : \"Returned if list name is not a string\"\n\"\" : \"Returned if request body is invalid JSON\"", + "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." + "message": "Returned if request body is invalid JSON" }, { - "field": null, - "message": "This campaign is already Paused." + "field": "name", + "message": "Returned if list name is not a string" }, { - "field": null, - "message": "This campaign is already Canceled." + "field": "name", + "message": "Returned if list name is a duplicate of an existing list or segment" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, - "404": { - "description": "\"\": \"not found\"", + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "not found" + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "A successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is" + ] }, "get": { + "description": "Returns an empty list if you GET and no lists exist on your account.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List All Lists", "consumes": [ "application/json" ], - "description": "View the time that this campaign is 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": "View Scheduled Time of a Campaign", - "parameters": [], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "send_at": 1490778528 - } - }, "schema": { + "title": "List All Lists response", + "type": "object", "properties": { - "send_at": { - "format": "int64", - "type": "integer" + "lists": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_list" + } } }, "required": [ - "send_at" - ], - "title": "View Scheduled Time of a Campaign response", - "type": "object" - } - }, - "404": { - "description": "\"\": \"not found\"", + "lists" + ] + }, "examples": { "application/json": { - "errors": [ + "lists": [ { - "field": null, - "message": "not found" + "id": 1, + "name": "the jones", + "recipient_count": 1 } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "Returns an empty list if you GET and no lists exist on your account.", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/subusers/{subuser_name}/monitor": { "parameters": [ { + "name": "subuser_name", "in": "path", - "name": "campaign_id", "required": true, "type": "string" } ], - "patch": { + "post": { + "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": "Create monitor settings", "consumes": [ "application/json" ], - "description": "Changes the send_at time for the specified campaign.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Update a Scheduled Campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { - "properties": { - "send_at": { - "format": "int64", - "type": "integer" - } - }, - "required": [ - "send_at" - ], - "title": "Update a Scheduled Campaign request", - "type": "object" + "$ref": "#/definitions/monitor" } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", "schema": { - "properties": { - "id": { - "description": "The campaign ID", - "type": "integer" - }, - "send_at": { - "description": "The unix timestamp to send the campaign.", - "type": "integer" - }, - "status": { - "description": "The status of the schedule.", - "type": "string" - } - }, - "required": [ - "id", - "send_at", - "status" - ], - "title": "Update a Scheduled Campaign response", - "type": "object" + "$ref": "#/definitions/monitor" + }, + "examples": { + "application/json": { + "email": "example@example.com", + "frequency": 50000 + } } }, "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", + "description": "", + "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." - }, + "message": "User already has a monitor" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ { "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" + "message": "authorization required" } ] } - }, + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "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 monitor settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "204": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": {} } }, - "403": { - "description": "\"send_at\": \"You cannot update the send_at value of non-scheduled campaign.\"", + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { - "field": "send_at", - "message": "You cannot update the send_at value of non-scheduled campaign." + "field": null, + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "404": { - "description": "\"\": \"not found\"", + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "not found" + "message": "No monitor settings for this user" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "Changes the send_at time for the specified campaign." + "summary": "" }, - "post": { + "put": { + "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": "Update Monitor Settings for a subuser", "consumes": [ "application/json" ], - "description": "Send your campaign at a specific date and time.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Schedule a Campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { - "properties": { - "send_at": { - "description": "The unix timestamp for the date and time you would like your campaign to be sent out.", - "type": "integer" - } - }, - "required": [ - "send_at" - ], - "title": "Schedule a Campaign request", - "type": "object" + "$ref": "#/definitions/monitor" } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "$ref": "#/definitions/monitor" + }, "examples": { "application/json": { - "id": 1234, - "send_at": 1489771528, - "status": "Scheduled" + "email": "example@example.com", + "frequency": 500 } - }, - "schema": { - "properties": { - "id": { - "description": "The campaign ID.", - "type": "integer" - }, - "send_at": { - "description": "The date time you scheduled your campaign to be sent.", - "type": "integer" - }, - "status": { - "description": "The status of your campaign.", - "enum": [ - "Scheduled" - ], - "type": "string" - } - }, - "required": [ - "id", - "send_at", - "status" - ], - "title": "Schedule a Campaign response", - "type": "object" } }, "400": { - "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", + "description": "", + "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" + "field": "email", + "message": "Email is required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ @@ -3532,893 +2774,617 @@ } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "403": { - "description": "\"\": \"You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.\"", - "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." - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"\": \"not found\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - } - }, - "/campaigns/{campaign_id}/schedules/now": { - "parameters": [ - { - "in": "path", - "name": "campaign_id", - "required": true, - "type": "string" - } - ], - "post": { + ] + }, + "get": { + "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": "Retrieve monitor settings for a subuser", "consumes": [ "application/json" ], - "description": "Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Send a Campaign", - "parameters": [ - { - "description": "The id of the campaign", - "in": "query", - "name": "campaign_id", - "required": true, - "type": "number" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "201": { + "200": { "description": "", - "examples": { - "application/json": { - "id": 1234, - "status": "Scheduled" - } - }, "schema": { - "properties": { - "id": { - "format": "int64", - "type": "integer" - }, - "status": { - "type": "string" - } - }, - "required": [ - "id", - "status" - ], - "title": "Send a Campaign response", - "type": "object" - } - }, - "400": { - "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", + "$ref": "#/definitions/monitor" + }, "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" - } - ] + "email": "example@example.com", + "frequency": 500 } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - }, - "403": { - "description": "\"\": \"You may only send a campaign when it is in draft mode.\"", + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "You may only send a campaign when it is in draft mode." + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "404": { - "description": "\"\": \"not found\"", + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "not found" + "message": "No monitor settings for this user" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/campaigns/{campaign_id}/schedules/test": { + "/whitelabel/links/{link_id}/subuser": { "parameters": [ { + "name": "link_id", "in": "path", - "name": "campaign_id", + "description": "The id of the link whitelabel you want to associate.", "required": true, - "type": "string" + "type": "integer" } ], "post": { + "description": "**This endpoint allows you to associate a link whitelabel with a subuser account.**\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": "Associate a Link Whitelabel", "consumes": [ "application/json" ], - "description": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Send a Test Campaign", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", - "name": "campaign_id", - "type": "string" - }, - { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "to": { - "description": "The email address that should receive the test campaign.", - "format": "email", - "type": "string" + "username": { + "type": "string", + "description": "The username of the subuser account that you want to associate the link whitelabel with." } - }, - "required": [ - "to" - ], - "type": "object" + } } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", "schema": { - "properties": { - "to": { - "type": "string" - } - }, - "required": [ - "to" - ], - "title": "Send a Test Campaign request", - "type": "object" - } - }, - "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"sender_id\": \"Please assign a sender identity to your campaign before sending a test.\"", - "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" - } - ] - } + "$ref": "#/definitions/link_whitelabel" }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"\": \"not found\"", "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "not found" + "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" } - ] + } } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]" + ] } }, - "/categories": { + "/whitelabel/links/subuser": { + "parameters": [], "get": { + "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": "Retrieve Associated Link Whitelabel", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get categories", - "parameters": [ - { - "in": "query", - "name": "limit", - "type": "string" - }, - { - "in": "query", - "name": "sort_by", - "type": "string" - }, + "produces": [ + "application/json" + ], + "parameters": [ { + "name": "username", "in": "query", - "name": "order", + "description": "The username of the subuser to retrieve associated link whitelabels for.", + "required": true, "type": "string" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": [ - { - "category": "category 1" - }, - { - "category": "category 2" - } - ] - }, "schema": { - "items": { - "properties": { - "category": { - "type": "string" + "$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" } - }, - "type": "object" - }, - "type": "array" + } + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [] - }, - "/categories/stats": { - "get": { + "delete": { + "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": "Disassociate a Link Whitelabel", "consumes": [ "application/json" ], - "description": "", - "operationId": "Category Stats provide all of your user\u2019s email statistics for your categories.", + "produces": [], "parameters": [ { + "name": "username", "in": "query", - "name": "start_date", - "required": true, - "type": "string" - }, - { - "in": "query", - "name": "end_date", - "type": "string" - }, - { - "in": "query", - "name": "categories", + "description": "The username of the subuser account that you want to disassociate a link whitelabel from.", "required": true, "type": "string" - }, - { - "in": "query", - "name": "limit", - "type": "string" - }, - { - "in": "query", - "name": "offset", - "type": "string" - }, + } + ], + "responses": { + "204": { + "description": "" + } + }, + "summary": "Link Whitelabels can be associated with subusers via parent accounts. This functionality allows\nsubusers to send mail o", + "security": [ { - "in": "query", - "name": "aggregated_by", - "type": "string" + "Authorization": [] } + ] + } + }, + "/contactdb/segments": { + "parameters": [], + "get": { + "description": "Get all your segments.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List All Segments", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": [ - { - "date": "2015-10-01", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "docs", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "mattscategory", - "type": "category" - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "docs", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "mattscategory", - "type": "category" - } - ] + "schema": { + "title": "List All Segments response", + "type": "object", + "properties": { + "segments": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_segments" + } } + }, + "required": [ + "segments" ] }, - "schema": { - "items": { - "properties": { - "date": { - "type": "string" + "examples": { + "application/json": { + "segments": [ + { + "id": 1234, + "name": "Age segments < 25", + "conditions": [ + { + "field": "age", + "value": "25", + "operator": "lt" + } + ], + "recipient_count": 8 }, - "stats": { - "items": { - "properties": { - "metrics": { - "properties": { - "blocks": { - "type": "number" - }, - "bounce_drops": { - "type": "number" - }, - "bounces": { - "type": "number" - }, - "clicks": { - "type": "number" - }, - "deferred": { - "type": "number" - }, - "delivered": { - "type": "number" - }, - "invalid_emails": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "processed": { - "type": "number" - }, - "requests": { - "type": "number" - }, - "spam_report_drops": { - "type": "number" - }, - "spam_reports": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - }, - "unsubscribe_drops": { - "type": "number" - }, - "unsubscribes": { - "type": "number" - } - }, - "type": "object" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } + { + "id": 2345, + "name": "email address - gmail", + "conditions": [ + { + "field": "email", + "value": "@gmail.com", + "operator": "contains" } - }, - "type": "array" + ], + "recipient_count": 0 } - }, - "type": "object" - }, - "type": "array" + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [] - }, - "/categories/stats/sums": { - "get": { + "post": { + "description": "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment 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. \n\nSegments 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\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Create a Segment", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get sums of a category's stats [Needs: Stats object defined, has category ID?]", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", - "name": "sort_by_metric", - "type": "string" - }, - { - "in": "query", - "name": "sort_by_direction", - "type": "string" - }, - { - "in": "query", - "name": "start_date", - "required": true, - "type": "string" - }, - { - "in": "query", - "name": "end_date", - "type": "string" - }, - { - "in": "query", - "name": "limit", - "type": "string" - }, - { - "in": "query", - "name": "offset", - "type": "string" - }, - { - "in": "query", - "name": "aggregated_by", - "type": "string" + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/contactdb_segments" + } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "$ref": "#/definitions/contactdb_segments_with_id" + }, "examples": { "application/json": { - "date": "2009-08-15", - "stats": [] + "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\"\n\"list_id\" : \"Returned if the list_id is not valid\"\n\"and_or\" : \"Returned if and_or and set value is not passed into the request body\"\n\"and_or\" : \"Returned if and_or is set on the only condition passed\"\n\"and_or\" : \"Returned if and_or is set on all conditions\"\n\"and_or\" : \"Returned if and_or is not set on more than one condition and less than all conditions\"\n\"operator\" : \"Returned if operator and set value is not passed into the request body\"\n\"value\" : \"Returned if value and set value is not passed into the request body\"\n\"field\" : \"Returned if field and set value is not passed into the request body\"\n\"\" : \"Returned if request body is not valid json\"\n\"\" : \"Returned if invalid value is passed into one of the request body parameters\"", "schema": { - "properties": { - "date": { - "type": "string" - }, - "stats": { - "items": { - "properties": {}, - "type": "object" + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "request body is not valid json" }, - "type": "array" - } - }, - "type": "object" + { + "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" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [] + ] + } }, - "/clients/stats": { - "get": { + "/contactdb/segments/{segment_id}": { + "parameters": [ + { + "name": "segment_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "description": "Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment.\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 a Segment", "consumes": [ "application/json" ], - "description": "Gets email statistics by client type.", - "operationId": "Retrieve stats by client type", + "produces": [ + "application/json" + ], "parameters": [ { + "name": "delete_contacts", "in": "query", - "name": "start_date", - "type": "string" - }, - { - "in": "query", - "name": "end_date", - "type": "string" - }, - { - "in": "query", - "name": "aggregated_by", - "type": "string" + "description": "True to delete all contacts matching the segment in addition to deleting the segment", + "type": "boolean" } ], - "produces": [ - "application/json" - ], "responses": { - "200": { + "204": { "description": "", + "schema": { + "type": "null" + } + }, + "400": { + "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not a valid boolean\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "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" - } - ] - } - ] + "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" + } + ] + } + } + }, + "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": { - "items": { - "properties": { - "date": { - "type": "string" - }, - "stats": { - "items": { - "properties": { - "metrics": { - "properties": { - "opens": { - "type": "integer" - }, - "unique_opens": { - "type": "integer" - } - }, - "type": "object" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "segment_id", + "message": "segment_id does not exist" } - }, - "type": "object" - }, - "type": "array" + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Gets email statistics by client type." + ] }, - "parameters": [] - }, - "/clients/{client_type}/stats": { "get": { + "description": "Get a single segment 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": "Retrieve a Segment", "consumes": [ "application/json" ], - "description": "Gets email statistics by a single client type.", - "operationId": "Retrieve stats by a specific client type", + "produces": [ + "application/json" + ], "parameters": [ { + "name": "segment_id", "in": "query", - "name": "start_date", - "type": "string" - }, - { - "in": "query", - "name": "end_date", - "type": "string" - }, - { - "in": "query", - "name": "aggregated_by", - "type": "string" + "description": "The ID of the segment you want to request.", + "required": true, + "type": "number" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/stats" + "$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 + } } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "Gets email statistics by a single client type." - }, - "parameters": [ - { - "in": "path", - "name": "client_type", - "required": true, - "type": "string" - } - ] - }, - "/contactdb/custom_fields": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Get 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": "List All Custom Fields", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", + }, + "400": { + "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { - "lists": [ + "errors": [ { - "id": 1, - "name": "the jones", - "recipient_count": 1 + "message": "if segment_id is not valid" } ] } - }, - "schema": { - "properties": { - "custom_fields": { - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id" - }, - "type": "array" - } - }, - "required": [ - "custom_fields" - ], - "title": "List All Custom Fields response", - "type": "object" } }, "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ @@ -4428,230 +3394,254 @@ } ] } - }, + } + }, + "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" + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [], - "post": { + "patch": { + "description": "Update a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Update a segment", "consumes": [ "application/json" ], - "description": "Create a custom field.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Create a Custom Field", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", + "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" }, - "type": { - "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" + } } }, - "type": "object" + "required": [ + "name" + ] } } ], - "produces": [ - "application/json" - ], "responses": { - "201": { + "200": { "description": "", + "schema": { + "$ref": "#/definitions/contactdb_segments" + }, "examples": { "application/json": { - "id": 1, - "name": "pet", - "type": "text" - } - }, - "schema": { - "properties": { - "id": { - "type": "integer" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - }, - "type": "object" + "id": 5, + "name": "The Millers", + "list_id": 5, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" + } + ], + "recipient_count": 1 + } } }, "400": { - "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { - "field": null, - "message": "Returned if request body is invalid JSON" + "message": "request body is not valid json" }, { - "field": "type", - "message": "Returned if custom field type is invalid or not provided" + "message": "invalid value is passed into one of the request body parameters" }, { - "field": "name", - "message": "Returned if custom field name is not provided" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/contactdb/custom_fields/{custom_field_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "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 a Custom Field", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "202": { - "description": "", - "examples": { - "application/json": { - "message": "Custom Field delete is processing." - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "400": { - "description": "\"id\" : \"Returned if custom_field_id is not valid\"", - "examples": { - "application/json": { - "errors": [ + "segment_id": "segment_id", + "message": "segment id is not valid" + }, { - "message": "Custom field in use by one or more segment conditions" + "field": "field", + "message": "field and set value is not passed into the request body" }, { - "message": "Custom field ID does not exist" + "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" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", + }, "examples": { "application/json": { "errors": [ { - "message": "Custom field ID does not exist" + "field": null, + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/contactdb/recipients/{recipient_id}/lists": { + "parameters": [ + { + "name": "recipient_id", + "in": "path", + "required": true, + "type": "string" + } + ], "get": { + "description": "Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to.\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 the Lists the Recipient Is On", "consumes": [ "application/json" ], - "description": "Get 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 a Custom Field", + "produces": [ + "application/json" + ], "parameters": [ { - "description": "The ID of the custom field you would like to retrieve", + "name": "recipient_id", "in": "query", - "name": "custom_field_id", + "description": "The ID of the recipient you are requesting lists for.", "required": true, - "type": "number" + "type": "string" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "type": "object", + "properties": { + "lists": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_list" + } + } + } + }, "examples": { "application/json": { - "id": 1, - "name": "pet", - "type": "text" + "lists": [ + { + "id": 1234, + "name": "Example list", + "recipient_count": 42 + } + ] } - }, - "schema": { - "$ref": "#/definitions/contactdb_custom_field_with_id" } }, "400": { - "description": "", + "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { - "message": "invalid id" + "field": null, + "message": "recipient ID is invalid" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ @@ -4661,79 +3651,89 @@ } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "404": { - "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", + "description": "\"recipient_id\" : \"Returned if record for the recipient id does not exist\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { - "message": "Custom field ID does not exist" + "field": null, + "message": "recipient id not found" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/contactdb/recipients/{recipient_id}": { "parameters": [ { + "name": "recipient_id", "in": "path", - "name": "custom_field_id", "required": true, "type": "string" } - ] - }, - "/contactdb/lists": { + ], "delete": { + "description": "Delete a single recipient from your contact database, 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 a Recipient", "consumes": [ "application/json" ], - "description": "Delete multiple lists.\n\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 Multiple lists", - "parameters": [], "produces": [ "application/json" ], + "parameters": [ + { + "name": "recipient_id", + "in": "query", + "description": "The ID of the recipient to be deleted.", + "required": true, + "type": "string" + } + ], "responses": { "204": { "description": "", "schema": { - "type": "null" + "type": "object", + "properties": {} } }, "400": { - "description": "\"id\" : \"Returned if all list ids are not valid\"", + "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "list id was invalid" + "message": "recipient not found" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ @@ -4743,135 +3743,168 @@ } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + } + }, + "404": { + "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "recipient_id is not valid" + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, "get": { + "description": "Retrieve a single recipient by ID from your contact database.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Retrieve a single recipient", "consumes": [ "application/json" ], - "description": "Returns an empty list if you GET and no lists exist on your account.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List All Lists", - "parameters": [], "produces": [ "application/json" ], + "parameters": [ + { + "name": "recipient_id", + "in": "query", + "description": "The ID of the created recipient.", + "type": "string" + } + ], "responses": { "200": { "description": "", + "schema": { + "$ref": "#/definitions/contactdb_recipient" + } + }, + "400": { + "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"" + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { - "lists": [ + "errors": [ { - "id": 1, - "name": "the jones", - "recipient_count": 1 + "field": null, + "message": "authorization required" } ] } - }, - "schema": { - "properties": { - "lists": { - "items": { - "$ref": "#/definitions/contactdb_list" - }, - "type": "array" - } - }, - "required": [ - "lists" - ], - "title": "List All Lists response", - "type": "object" } + }, + "404": { + "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"" } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Returns an empty list if you GET and no lists exist on your account." - }, + ] + } + }, + "/contactdb/recipients/search": { "parameters": [], - "post": { + "get": { + "description": "Search the recipients in your contactdb.\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 Recipients Matching Search Criteria", "consumes": [ "application/json" ], - "description": "Create a list for your 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": "Create a List", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", - "name": "body", - "schema": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "title": "Create a List request", - "type": "object" - } + "name": "{field_name}", + "in": "query", + "type": "string" } ], - "produces": [ - "application/json" - ], "responses": { - "201": { + "200": { "description": "", + "schema": { + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_recipient" + } + } + } + }, "examples": { "application/json": { - "id": 1, - "name": "your list name", - "recipient_count": 0 + "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" + } + ] + } + ] } - }, - "schema": { - "$ref": "#/definitions/contactdb_list" } }, "400": { - "description": "\"name\" : \"Returned if list name is a duplicate of an existing list or segment\"\n\"name\" : \"Returned if list name is not a string\"\n\"\" : \"Returned if request body is invalid JSON\"", + "description": "\"\" : \"Returned if no search params are specified\"\n\"field\" : \"Returned if the provided field is invalid or does not exist\"", + "schema": { + "$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" + "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" }, { - "field": "name", - "message": "Returned if list name is a duplicate of an existing list or segment" + "message": "No search params are specified" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ @@ -4881,6296 +3914,6067 @@ } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "{% info %}\n\"field_name\"* is a variable that is substituted for your actual custom field name from your recipient.\nText f", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/contactdb/lists/{list_id}": { + "/contactdb/recipients": { + "parameters": [], "delete": { + "description": "Deletes one or more recipients. The body is a list of recipient ids to delete.\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 Recipient", "consumes": [ "application/json" ], - "description": "Delete a list 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 a List", - "parameters": [ - { - "description": "Adds the ability to delete all contacts on the list in addition to deleting the list.", - "enum": [ - true, - false - ], - "in": "query", - "name": "delete_contacts", - "type": "boolean" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "202": { - "description": "", - "schema": { - "type": "null" - } + "200": { + "description": "" }, "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not valid\"", + "description": "\"\" : \"Returned if no recipients are deleted\"\n\"\" : \"Returned if all of the provided recipient ids are invalid\"\n\"\" : \"Returned if request body is not valid json\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { - "field": "delete_contacts", - "message": "delete_contacts not a bool" - }, - { - "field": "list_id", - "message": "Returned if list_id is not valid" + "message": "No recipient ids provided" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } }, "401": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", + }, "examples": { "application/json": { "errors": [ { - "message": "List not found: 5" + "field": null, + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "Deletes one or more recipients. The body is a list of recipient ids to delete.", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "get": { + "patch": { + "description": "Updates one or more recipients. The body is an array of recipient objects.\n\nIt 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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Update Recipient", "consumes": [ "application/json" ], - "description": "Get a single list. \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 a single list.", - "parameters": [ - { - "description": "The ID of the list to retrieve.", - "in": "query", - "name": "list_id", - "type": "number" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "200": { + "201": { "description": "", - "examples": { - "application/json": { - "id": 1, - "name": "listname", - "recipient_count": 0 - } - }, "schema": { - "$ref": "#/definitions/contactdb_list" + "$ref": "#/definitions/contactdb_recipient_response" } }, "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" - } - ] - } - }, + "description": "\"\" : \"Returned if request body is not valid json\"", "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", "examples": { "application/json": { "errors": [ { "field": null, - "message": "List ID does not exist" + "message": "Request body is not valid json" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "list_id", - "required": true, - "type": "string" - } - ], - "patch": { - "consumes": [ - "application/json" - ], - "description": "Update the name of a list.\n\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Update a List", - "parameters": [ - { - "description": "The ID of the list you are updating.", - "in": "query", - "name": "list_id", - "required": true, - "type": "number" }, - { - "in": "body", - "name": "body", - "schema": { - "properties": { - "name": { - "description": "The new name for your list. ", - "type": "string" - } - }, - "required": [ - "name" - ], - "title": "Update a List request", - "type": "object" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { + "401": { "description": "", - "schema": { - "properties": {}, - "type": "object" - } - }, - "400": { - "description": "\"name\" : \"Returned if list name is a duplicate of existing list or segment\"\n\"name\" : \"Returned if list name is invalid or not provided\"\n\"list_id\" : \"Returned if list_id is not valid\"\n\"\" : \"Returned if request body is invalid JSON\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "List ID does not exist" - } - ] - } - }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/contactdb/lists/{list_id}/recipients": { - "get": { - "consumes": [ - "application/json" - ], - "description": "List all the recipients currently on a specific list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients on a List", - "parameters": [ - { - "description": "Page index of first recipient to return (must be a positive integer)", - "in": "query", - "name": "page", - "type": "integer" - }, - { - "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", - "in": "query", - "name": "page_size", - "type": "integer" - }, - { - "description": "The ID of the list whose recipients you are requesting.", - "in": "query", - "name": "list_id", - "required": true, - "type": "number" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "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 - } - ] - } }, - "schema": { - "properties": { - "recipients": { - "items": { - "$ref": "#/definitions/contactdb_recipient" - }, - "type": "array" - } - }, - "type": "object" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"", "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" + "field": null, + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - } - ] - } - }, - "schema": { - "properties": {}, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "list_id", - "required": true, - "type": "string" - } - ], - "post": { - "consumes": [ - "application/json" - ], - "description": "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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Add Multiple Recipients to a List", - "parameters": [ - { - "description": "The list to add your recipients to. ", - "in": "query", - "name": "list_id", - "required": true, - "type": "number" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"\" : \"Returned if no valid recipient ids were passed\"\n\"\" : \"Returned if no recipients were added\"\n\"\" : \"Returned if request body is invalid JSON\"", - "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" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\": \"Returned if list_id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "list_id does not exist" - }, - { - "field": "recipient_id", - "message": "recipient_id does not exist" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they " - } - }, - "/contactdb/lists/{list_id}/recipients/{recipient_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "Delete a single recipient from a list.\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 a Single Recipient from a Single List", - "parameters": [ - { - "description": "The ID of the list you are taking this recipient away from.", - "in": "query", - "name": "list_id", - "required": true, - "type": "number" - }, - { - "description": "The ID of the recipient to take off the list.", - "in": "query", - "name": "recipient_id", - "required": true, - "type": "number" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "no valid recipients were provided" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "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" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "list_id", - "required": true, - "type": "string" - }, - { - "in": "path", - "name": "recipient_id", - "required": true, - "type": "string" - } - ], - "post": { - "consumes": [ - "application/json" - ], - "description": "Add a recipient to a list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Add a Single Recipient to a List", - "parameters": [ - { - "description": "The ID of the list to add the recipient to.", - "in": "query", - "name": "list_id", - "type": "number" - }, - { - "description": "The recipient you are adding to the list indicated.", - "in": "query", - "name": "recipient_id", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is invalid\"\n\"recipient_id\" : \"Returned if recipient_id is invalid\"", - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id is invalid" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "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" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/contactdb/recipients": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "Deletes one or more recipients. The body is a list of recipient ids to delete.\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 Recipient", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "" - }, - "400": { - "description": "\"\" : \"Returned if no recipients are deleted\"\n\"\" : \"Returned if all of the provided recipient ids are invalid\"\n\"\" : \"Returned if request body is not valid json\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "No recipient ids provided" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "Deletes one or more recipients. The body is a list of recipient ids to delete." - }, - "get": { - "consumes": [ - "application/json" - ], - "description": "Batch 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 contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients [waiting on Bryan Adamson's response]", - "parameters": [ - { - "description": "Page index of first recipients to return (must be a positive integer)", - "in": "query", - "name": "page", - "type": "integer" - }, - { - "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", - "in": "query", - "name": "page_size", - "type": "integer" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "properties": { - "recipients": { - "items": { - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "recipients" - ], - "title": "List Recipients response", - "type": "object" - } - }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"" - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "{% info %}\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\n" - }, - "parameters": [], - "patch": { - "consumes": [ - "application/json" - ], - "description": "Updates one or more recipients. The body is an array of recipient objects.\n\nIt 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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Update Recipient", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient_response" - } - }, - "400": { - "description": "\"\" : \"Returned if request body is not valid json\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "Updates one or more recipients. The body is a list of recipient objects." - }, - "post": { - "consumes": [ - "application/json" - ], - "description": "Add a recipient to your contactdb. 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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Add recipients", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "examples": { - "application/json": { - "error_count": 1, - "error_indices": [ - 2 - ], - "errors": [ - { - "error_indices": [ - 2 - ], - "message": "Invalid email." - } - ], - "new_count": 2, - "persisted_recipients": [ - "YUBh", - "bWlsbGVyQG1pbGxlci50ZXN0" - ], - "updated_count": 0 - } - }, - "schema": { - "$ref": "#/definitions/contactdb_recipient_response" - } - }, - "400": { - "description": "\"\" : \"Returned if request body is not valid json\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/contactdb/recipients/billable_count": { - "get": { - "consumes": [ - "application/json" - ], - "description": "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.\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 the count of billable recipients", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "recipient_count": 1234 - } - }, - "schema": { - "$ref": "#/definitions/contactdb_recipient_count" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [] - }, - "/contactdb/recipients/count": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Get a count of the current number of recipients in your contact database.\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 a Count of Recipients", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "recipient_count": 1234 - } - }, - "schema": { - "$ref": "#/definitions/contactdb_recipient_count" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [] - }, - "/contactdb/recipients/search": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Search the recipients in your contactdb.\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 Recipients Matching Search Criteria", - "parameters": [ - { - "in": "query", - "name": "{field_name}", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "recipients": [ - { - "created_at": 1422313607, - "custom_fields": [ - { - "id": 23, - "name": "pet", - "type": "text", - "value": "Fluffy" - } - ], - "email": "jones@example.com", - "first_name": null, - "id": "YUBh", - "last_clicked": null, - "last_emailed": null, - "last_name": "Jones", - "last_opened": null, - "updated_at": 1422313790 - } - ] - } - }, - "schema": { - "properties": { - "recipients": { - "items": { - "$ref": "#/definitions/contactdb_recipient" - }, - "type": "array" - } - }, - "type": "object" - } - }, - "400": { - "description": "\"\" : \"Returned if no search params are specified\"\n\"field\" : \"Returned if the provided field is invalid or does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" - }, - { - "message": "No search params are specified" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "{% info %}\n\"field_name\"* is a variable that is substituted for your actual custom field name from your recipient.\nText f" - }, - "parameters": [] - }, - "/contactdb/recipients/{recipient_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "Delete a single recipient from your contact database, 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 a Recipient", - "parameters": [ - { - "description": "The ID of the recipient to be deleted.", - "in": "query", - "name": "recipient_id", - "required": true, - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient not found" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient_id is not valid" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "get": { - "consumes": [ - "application/json" - ], - "description": "Retrieve a single recipient by ID from your contact database.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Retrieve a single recipient", - "parameters": [ - { - "description": "The ID of the created recipient.", - "in": "query", - "name": "recipient_id", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient" - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"" - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "recipient_id", - "required": true, - "type": "string" - } - ] - }, - "/contactdb/recipients/{recipient_id}/lists": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to.\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 the Lists the Recipient Is On", - "parameters": [ - { - "description": "The ID of the recipient you are requesting lists for.", - "in": "query", - "name": "recipient_id", - "required": true, - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "lists": [ - { - "id": 1234, - "name": "Example list", - "recipient_count": 42 - } - ] - } - }, - "schema": { - "properties": { - "lists": { - "items": { - "$ref": "#/definitions/contactdb_list" - }, - "type": "array" - } - }, - "type": "object" - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient ID is invalid" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for the recipient id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient id not found" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "recipient_id", - "required": true, - "type": "string" - } - ] - }, - "/contactdb/reserved_fields": { - "get": { - "consumes": [ - "application/json" - ], - "description": "List fields that are reserved and can't be used for custom field names. [GET]\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 reserved custom fields fields.", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "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" - } - ] - } - }, - "schema": { - "properties": { - "reserved_fields": { - "description": "The reserved fields that are already set up within custom fields.", - "items": { - "$ref": "#/definitions/contactdb_custom_field" - }, - "type": "array" - } - }, - "required": [ - "reserved_fields" - ], - "title": "List fields that are reserved and can't be used for custom field names. response", - "type": "object" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [] - }, - "/contactdb/segments": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Get all your segments.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List All Segments", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "segments": [ - { - "conditions": [ - { - "field": "age", - "operator": "lt", - "value": "25" - } - ], - "id": 1234, - "name": "Age segments < 25", - "recipient_count": 8 - }, - { - "conditions": [ - { - "field": "email", - "operator": "contains", - "value": "@gmail.com" - } - ], - "id": 2345, - "name": "email address - gmail", - "recipient_count": 0 - } - ] - } - }, - "schema": { - "properties": { - "segments": { - "items": { - "$ref": "#/definitions/contactdb_segments" - }, - "type": "array" - } - }, - "required": [ - "segments" - ], - "title": "List All Segments response", - "type": "object" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "post": { - "consumes": [ - "application/json" - ], - "description": "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment 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. \n\nSegments 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\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Create a Segment", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "$ref": "#/definitions/contactdb_segments" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "conditions": [ - { - "and_or": "", - "field": "last_name", - "operator": "eq", - "value": "Miller" - }, - { - "and_or": "and", - "field": "last_clicked", - "operator": "gt", - "value": "01/02/2015" - }, - { - "and_or": "or", - "field": "clicks.campaign_identifier", - "operator": "eq", - "value": "513" - } - ], - "id": 1, - "list_id": 4, - "name": "Last Name Miller", - "recipient_count": 0 - } - }, - "schema": { - "$ref": "#/definitions/contactdb_segments_with_id" - } - }, - "400": { - "description": "\"name\" : \"Returned if the name is not valid\"\n\"list_id\" : \"Returned if the list_id is not valid\"\n\"and_or\" : \"Returned if and_or and set value is not passed into the request body\"\n\"and_or\" : \"Returned if and_or is set on the only condition passed\"\n\"and_or\" : \"Returned if and_or is set on all conditions\"\n\"and_or\" : \"Returned if and_or is not set on more than one condition and less than all conditions\"\n\"operator\" : \"Returned if operator and set value is not passed into the request body\"\n\"value\" : \"Returned if value and set value is not passed into the request body\"\n\"field\" : \"Returned if field and set value is not passed into the request body\"\n\"\" : \"Returned if request body is not valid json\"\n\"\" : \"Returned if invalid value is passed into one of the request body parameters\"", - "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" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/contactdb/segments/{segment_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment.\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 a Segment", - "parameters": [ - { - "description": "True to delete all contacts matching the segment in addition to deleting the segment", - "in": "query", - "name": "delete_contacts", - "type": "boolean" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not a valid boolean\"", - "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" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "field": "segment_id", - "message": "segment_id does not exist" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "get": { - "consumes": [ - "application/json" - ], - "description": "Get a single segment 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": "Retrieve a Segment", - "parameters": [ - { - "description": "The ID of the segment you want to request.", - "in": "query", - "name": "segment_id", - "required": true, - "type": "number" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "conditions": [ - { - "and_or": "", - "field": "last_name", - "operator": "eq", - "value": "Miller" - } - ], - "id": 1, - "list_id": 4, - "name": "Last Name Miller", - "recipient_count": 1 - } - }, - "schema": { - "$ref": "#/definitions/contactdb_segments" - } - }, - "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "if segment_id is not valid" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "examples": { - "application/json": { - "errors": [ - { - "message": "segment_id not found" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "segment_id", - "required": true, - "type": "string" - } - ], - "patch": { - "consumes": [ - "application/json" - ], - "description": "Update a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Update a segment", - "parameters": [ - { - "description": "The ID of the segment you are updating.", - "in": "query", - "name": "segment_id", - "type": "string" - }, - { - "in": "body", - "name": "body", - "schema": { - "properties": { - "conditions": { - "description": "The conditions by which this segment should be created.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - }, - "type": "array" - }, - "list_id": { - "description": "The list ID you would like this segment to be built from.", - "type": "number" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "type": "object" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "conditions": [ - { - "and_or": "", - "field": "last_name", - "operator": "eq", - "value": "Miller" - } - ], - "id": 5, - "list_id": 5, - "name": "The Millers", - "recipient_count": 1 - } - }, - "schema": { - "$ref": "#/definitions/contactdb_segments" - } - }, - "400": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "message": "segment id is not valid", - "segment_id": "segment_id" - }, - { - "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" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/contactdb/segments/{segment_id}/recipients": { - "get": { - "consumes": [ - "application/json" - ], - "description": "List all of the recipients in a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients On a Segment", - "parameters": [ - { - "in": "query", - "name": "page", - "type": "string" - }, - { - "in": "query", - "name": "page_size", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "properties": { - "recipients": { - "items": { - "properties": {}, - "type": "object" - }, - "type": "array" - } - }, - "required": [ - "recipients" - ], - "title": "List Recipients On a Segment response", - "type": "object" - } - }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"" - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "segment_id", - "required": true, - "type": "string" - } - ] - }, - "/devices/stats": { - "get": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Gets email statistics by device type.", - "parameters": [ - { - "in": "query", - "name": "end_date", - "type": "string" - }, - { - "in": "query", - "name": "limit", - "type": "string" - }, - { - "in": "query", - "name": "offset", - "type": "string" - }, - { - "in": "query", - "name": "aggregated_by", - "type": "string" - }, - { - "in": "query", - "name": "start_date", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "opens": 2, - "unique_opens": 2 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Webmail", - "type": "device" - } - ] + } + } + }, + "summary": "Updates one or more recipients. The body is a list of recipient objects.", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "Batch 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 contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List Recipients [waiting on Bryan Adamson's response]", + "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" + } + ], + "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\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"" + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "{% info %}\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\n", + "security": [ + { + "Authorization": [] + } + ] + }, + "post": { + "description": "Add a recipient to your contactdb. 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.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Add recipients", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "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": { - "items": { - "properties": { - "date": { - "type": "string" + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "Request body is not valid json" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists/{list_id}/recipients/{recipient_id}": { + "parameters": [ + { + "name": "list_id", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "recipient_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "description": "Delete a single recipient from a list.\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 a Single Recipient from a Single List", + "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" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"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" }, - "stats": { - "items": { - "properties": { - "metrics": { - "properties": { - "opens": { - "type": "number" - }, - "unique_opens": { - "type": "number" - } - }, - "type": "object" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - }, - "type": "array" + { + "field": "recipient_id", + "message": "no valid recipients were provided" + } + ] + } + } + }, + "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\"\n\"recipient_id\" : \"Returned if 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" } - }, - "type": "object" - }, - "type": "array" + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [] - }, - "/geo/stats": { - "get": { + "post": { + "description": "Add a recipient to a list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Add a Single Recipient to a List", "consumes": [ "application/json" ], - "description": "", - "operationId": "Gets email statistics by country and state/province.", + "produces": [ + "application/json" + ], "parameters": [ { + "name": "list_id", "in": "query", - "name": "limit", - "type": "string" + "description": "The ID of the list to add the recipient to.", + "type": "number" }, { + "name": "recipient_id", "in": "query", - "name": "offset", + "description": "The recipient you are adding to the list indicated.", "type": "string" + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is invalid\"\n\"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 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\"\n\"recipient_id\" : \"Returned if 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" + } + ] + } + } + } + }, + "summary": "", + "security": [ { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists/{list_id}": { + "parameters": [ + { + "name": "list_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "description": "Delete a list 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 a List", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "delete_contacts", "in": "query", - "name": "aggregated_by", - "type": "string" + "description": "Adds the ability to delete all contacts on the list in addition to deleting the list.", + "type": "boolean", + "enum": [ + true, + false + ] + } + ], + "responses": { + "202": { + "description": "", + "schema": { + "type": "null" + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not valid\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "delete_contacts", + "message": "delete_contacts not a bool" + }, + { + "field": "list_id", + "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" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "Update the name of a list.\n\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Update a List", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ { + "name": "list_id", "in": "query", - "name": "start_date", - "type": "string" + "description": "The ID of the list you are updating.", + "required": true, + "type": "number" }, { - "in": "query", - "name": "end_date", - "type": "string" + "name": "body", + "in": "body", + "schema": { + "title": "Update a List request", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The new name for your list. " + } + }, + "required": [ + "name" + ] + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + }, + "400": { + "description": "\"name\" : \"Returned if list name is a duplicate of existing list or segment\"\n\"name\" : \"Returned if list name is invalid or not provided\"\n\"list_id\" : \"Returned if list_id is not valid\"\n\"\" : \"Returned if request body is invalid JSON\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + } }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "List ID does not exist" + } + ] + } + } + } + }, + "summary": "", + "security": [ { - "in": "query", - "name": "country", - "type": "string" + "Authorization": [] } + ] + }, + "get": { + "description": "Get a single list. \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 a single list.", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [ + { + "name": "list_id", + "in": "query", + "description": "The ID of the list to retrieve.", + "type": "number" + } + ], "responses": { "200": { "description": "", + "schema": { + "$ref": "#/definitions/contactdb_list" + }, "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 1, - "unique_clicks": 0, - "unique_opens": 1 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "application/json": { + "id": 1, + "name": "listname", + "recipient_count": 0 + } + } + }, + "400": { + "description": "\"list_id\" : \"Returned if list_id is not valid\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + } + }, + "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": [ + { + "field": null, + "message": "List ID does not exist" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/custom_fields": { + "parameters": [], + "get": { + "description": "Get 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": "List All Custom Fields", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "title": "List All Custom Fields response", + "type": "object", + "properties": { + "custom_fields": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_custom_field_with_id" + } + } + }, + "required": [ + "custom_fields" + ] + }, + "examples": { + "application/json": { + "lists": [ + { + "id": 1, + "name": "the jones", + "recipient_count": 1 + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "post": { + "description": "Create a custom field.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "Create a Custom Field", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" }, - { - "date": "2015-10-25", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "type": { + "type": "string" + } + } + } + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "type": "object", + "properties": { + "id": { + "type": "integer" }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "name": { + "type": "string" }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "type": { + "type": "string" + } + } + }, + "examples": { + "application/json": { + "id": 1, + "name": "pet", + "type": "text" + } + } + }, + "400": { + "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "Returned if request body is invalid JSON" + }, + { + "field": "type", + "message": "Returned if custom field type is invalid or not provided" + }, + { + "field": "name", + "message": "Returned if custom field name is not provided" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/custom_fields/{custom_field_id}": { + "parameters": [ + { + "name": "custom_field_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "description": "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 a Custom Field", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "202": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "message": "Custom Field delete is processing." + } + } + }, + "400": { + "description": "\"id\" : \"Returned if custom_field_id is not valid\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Custom field in use by one or more segment conditions" + }, + { + "message": "Custom field ID does not exist" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "Get 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 a Custom Field", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "custom_field_id", + "in": "query", + "description": "The ID of the custom field you would like to retrieve", + "required": true, + "type": "number" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contactdb_custom_field_with_id" + }, + "examples": { + "application/json": { + "id": 1, + "name": "pet", + "type": "text" + } + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/api_keys/{api_key_id}": { + "parameters": [ + { + "name": "api_key_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "patch": { + "description": "**Update the name of an existing API Key**\n\nA JSON request body with a \"name\" property is required.\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 updating.|", + "operationId": "Update API keys", + "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." + } + } + } + } + ], + "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" + } + ] + } + } + } + }, + "summary": "**Update the name of an existing API Key**\n\nA JSON request body with a \"name\" property is required.\n\nThe API Keys featur", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "Retrieve a single api key.\nIf the API Key ID does not exist an HTTP 404 will be returned.\n\n## URI Parameters\n\n| Param | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key for which you are requesting information.|", + "operationId": "Get an existing API Key", + "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." }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "scopes": { + "type": "array", + "description": "The individual permissions that you are giving to this API Key.", + "items": { + "type": "string" + } + } + }, + "required": [ + "name" + ] + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "_isOpen": true, + "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", + "properties": {} + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "unable to find API Key" + } + ] + } + } + } + }, + "summary": "Retrieve a single api key.\nIf the API Key ID does not exist an HTTP 404 will be returned.", + "security": [ + { + "Authorization": [] + } + ] + }, + "put": { + "description": "A JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.\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", + "operationId": "Update the name & scopes of an API Key", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } + "scopes": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + ], + "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", + "properties": {} + } + }, + "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" + } + ] + } + } + } + }, + "summary": "A JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.", + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "description": "**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", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "unable to find API Key" + } + ] + } + } + } + }, + "summary": "**Revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/scheduled_sends/{batch_id}": { + "parameters": [ + { + "name": "batch_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "patch": { + "description": "Update the status 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": "Update user scheduled send information", + "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" + ] + } + } + ], + "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" + } + ] + } + } + } + }, + "summary": "Update the status of a scheduled send.", + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "description": "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 a cancellation or pause of a scheduled send", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "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": "batch id not found" + } + ] + } + } + } + }, + "summary": "Delete the cancellation/pause of a scheduled send.", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "Get 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": "Retrieve scheduled send", + "consumes": [ + "application/json" + ], + "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": [ { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", + "status": "cancel" }, { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", + "status": "pause" + } + ] + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations\na", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/scheduled_sends": { + "parameters": [], + "post": { + "description": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.\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": "Cancel or pause a scheduled send", + "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]" }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } + "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" + ] + } + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/user_scheduled_send_status" + } + }, + "400": { + "description": "\"\" : \"max limit reached\"\n\"batch_id\" : \"invalid batch id\"\n\"batch_id\" : \"a status for this batch id exists, try PATCH to update the status\"", + "schema": { + "type": "object", + "properties": {} + }, + "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": {} + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "Get 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 all scheduled sends", + "consumes": [ + "application/json" + ], + "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" }, { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" + "batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2", + "status": "cancel" + } + ] + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/subusers/{subuser_name}": { + "parameters": [ + { + "name": "subuser_name", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "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 a subuser", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "This endpoint allows you to enable or disable a subuser.\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": "Enable/disable a subuser", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "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." + } + } + } + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + }, + "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" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/ips/assigned": { + "parameters": [], + "get": { + "description": "Retrieve a list of your IP addresses.", + "operationId": "List all assigned IPs", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "title": "List all assigned IPs response", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "pools": { + "type": "array", + "items": { + "type": "string" } - ] + }, + "warmup": { + "type": "boolean" + }, + "start_date": { + "type": "integer" + } + } + } + }, + "examples": { + "application/json": [ + { + "ip": "167.89.21.3", + "pools": [ + "new_test5" + ], + "warmup": true, + "start_date": 1409616000 + } + ] + } + } + }, + "summary": "See only assigned IPs.", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail_settings/plain_content": { + "parameters": [], + "get": { + "description": "", + "operationId": "Get plain content mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "examples": { + "application/json": { + "enabled": false + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "", + "operationId": "Update plain content mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + } + }, + "examples": { + "application/json": { + "enabled": false + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns/{campaign_id}/schedules": { + "parameters": [ + { + "name": "campaign_id", + "in": "path", + "required": true, + "type": "integer" + } + ], + "get": { + "description": "View the time that this campaign is 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": "View Scheduled Time of a Campaign", + "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" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "Changes the send_at time for the specified campaign.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Update a Scheduled Campaign", + "consumes": [ + "application/json" + ], + "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" + ] + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "title": "Update a Scheduled Campaign response", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The campaign ID" }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "send_at": { + "type": "integer", + "description": "The unix timestamp to send the campaign." }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "status": { + "type": "string", + "description": "The status of the schedule." + } + }, + "required": [ + "id", + "send_at", + "status" + ] + } + }, + "400": { + "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"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" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "summary": "Changes the send_at time for the specified campaign.", + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "description": "A 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": "Unschedule a Scheduled Campaign", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "403": { + "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"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" + } + ] + } + } + } + }, + "summary": "A successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is", + "security": [ + { + "Authorization": [] + } + ] + }, + "post": { + "description": "Send your campaign at a specific date and time.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Schedule a Campaign", + "consumes": [ + "application/json" + ], + "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" + ] + } + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "title": "Schedule a Campaign response", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The campaign ID." }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "send_at": { + "type": "integer", + "description": "The date time you scheduled your campaign to be sent." }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } + "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\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"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 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" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/suppression/bounces/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "description": "", + "operationId": "Get a Bounce", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "integer" + }, + "email": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + }, + "examples": { + "application/json": [ { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "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" + } + ] + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "description": "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. \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 a bounce", + "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" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail_settings/template": { + "parameters": [], + "get": { + "description": "", + "operationId": "Get template mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "html_content": { + "type": "string" + } + } + }, + "examples": { + "application/json": { + "enabled": false, + "html_content": "<% body %>Example
\n" + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "", + "operationId": "Update template mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "html_content": { + "type": "string" + } + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "TX", - "type": "province" - } - ] + "html_content": { + "type": "string" } - ] + } + }, + "examples": { + "application/json": { + "enabled": false, + "html_content": "<% body %>Example
\n" + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail_settings/address_whitelist": { + "parameters": [], + "get": { + "description": "", + "operationId": "Get address whitelist mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_settings_address_whitelabel" }, + "examples": { + "application/json": { + "enabled": false, + "list": [ + "example.com" + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "", + "operationId": "Update address whitelist mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", "schema": { - "items": { - "properties": { - "date": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "list": { + "type": "array", + "items": { "type": "string" - }, - "stats": { - "items": { - "properties": { - "metrics": { - "properties": { - "clicks": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - } - }, - "type": "object" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - }, - "type": "array" } - }, - "type": "object" - }, - "type": "array" + } + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_settings_address_whitelabel" + }, + "examples": { + "application/json": { + "enabled": true, + "list": [ + "email1@example.com" + ] + } } } }, - "summary": "" - }, - "parameters": [] + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } }, - "/ips": { + "/mail_settings/footer": { + "parameters": [], "get": { + "description": "", + "operationId": "Get footer mail settings [params can be null?]", "consumes": [ "application/json" ], - "description": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabel info.\nThe start_date field corresponds to when warmup started for that IP.", - "operationId": "List all IPs", - "parameters": [ - { - "description": "The IP address to get", - "in": "query", - "name": "ip", - "type": "string" - }, - { - "description": "Should we exclude whitelabels?", - "in": "query", - "name": "exclude_whitelabels", - "type": "string" - }, + "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" + } + } + } + }, + "summary": "", + "security": [ { - "description": "The subuser you are requesting for.", - "in": "query", - "name": "subuser", - "type": "string" - }, + "Authorization": [] + } + ] + }, + "patch": { + "description": "", + "operationId": "Update footer mail settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ { - "description": "The number of IPs you want returned at the same time.", - "in": "query", - "name": "limit", - "type": "string" - }, + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/mail_settings_footer" + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_settings_footer" + }, + "examples": { + "application/json": { + "enabled": true, + "html_content": "Example HTML content", + "plain_content": "Example plain content" + } + } + } + }, + "summary": "", + "security": [ { - "description": "The offset for the number of IPs that you are requesting.", - "in": "query", - "name": "offset", - "type": "string" + "Authorization": [] } + ] + } + }, + "/asm/suppressions/global/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "description": "", + "operationId": "Retrieve a Global Suppression", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": [ - { - "ip": "127.0.0.1", - "pools": [], - "rdns": "o1.em.example.com", - "start_date": 1250337600, - "subusers": [ - "example_subuser1", - "example_subuser2" - ], - "warmup": true, - "whitelabeled": true - }, - { - "ip": "127.0.0.1", - "pools": [], - "start_date": null, - "subusers": [], - "warmup": false, - "whitelabeled": false - } - ] - }, "schema": { - "items": { - "properties": { - "ip": { - "type": "string" - }, - "pools": { - "items": { - "properties": {}, - "type": "object" - }, - "type": "array" - }, - "rdns": { - "type": "string" - }, - "start_date": { - "type": [ - "number", - "null" - ] - }, - "subusers": { - "items": { - "type": "string" - }, - "type": "array" - }, - "warmup": { - "type": "boolean" - }, - "whitelabeled": { - "type": "boolean" - } - }, - "type": "object" + "title": "Retrieve a Global Suppression response", + "type": "object", + "properties": { + "recipient_email": { + "type": "string" + } }, - "type": "array" + "required": [ + "recipient_email" + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabe" + ] }, - "parameters": [] + "delete": { + "description": "", + "operationId": "Delete a Global Suppression", + "consumes": [ + "application/json" + ], + "produces": [], + "parameters": [], + "responses": { + "204": { + "description": "" + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } }, - "/ips/assigned": { + "/tracking_settings/google_analytics": { + "parameters": [], "get": { + "description": "", + "operationId": "Get Google Analytics Settings", "consumes": [ "application/json" ], - "description": "Retrieve a list of your IP addresses.", - "operationId": "List all assigned IPs", - "parameters": [], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", "schema": { + "type": "object", "properties": { - "ip": { + "enabled": { + "type": "boolean" + }, + "utm_campaign": { "type": "string" }, - "pools": { - "items": { - "type": "string" - }, - "type": "array" + "utm_content": { + "type": "string" }, - "start_date": { - "format": "int64", - "type": "integer" + "utm_medium": { + "type": "string" }, - "warmup": { - "type": "boolean" + "utm_source": { + "type": "string" + }, + "utm_term": { + "type": "string" } - }, - "required": [ - "ip", - "pools", - "warmup", - "start_date" - ], - "title": "List all assigned IPs response", - "type": "object" + } + }, + "examples": { + "application/json": { + "enabled": true, + "utm_campaign": "", + "utm_content": "lotsandlotsofcontent", + "utm_medium": "", + "utm_source": "", + "utm_term": "" + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "See only assigned IPs." + ] }, - "parameters": [] - }, - "/ips/pools": { - "get": { + "patch": { + "description": "", + "operationId": "Update Google Analytics Settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "List all IP pools.", - "parameters": [], - "produces": [], - "responses": { - "default": { - "description": "", - "schema": {} - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "post": { - "consumes": [ + "produces": [ "application/json" ], - "description": "", - "operationId": "Create an IP pool.", "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "name": { + "enabled": { + "type": "boolean" + }, + "utm_source": { + "type": "string" + }, + "utm_medium": { + "type": "string" + }, + "utm_term": { + "type": "string" + }, + "utm_content": { + "type": "string" + }, + "utm_campaign": { "type": "string" } - }, - "type": "object" + } } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "name": "marketing" - } - }, "schema": { + "type": "object", "properties": { - "name": { + "enabled": { + "type": "boolean" + }, + "utm_campaign": { + "type": "string" + }, + "utm_content": { + "type": "string" + }, + "utm_medium": { + "type": "string" + }, + "utm_source": { + "type": "string" + }, + "utm_term": { "type": "string" } - }, - "type": "object" + } + }, + "examples": { + "application/json": { + "enabled": true, + "utm_campaign": "", + "utm_content": "lotsandlotsofcontent", + "utm_medium": "", + "utm_source": "", + "utm_term": "" + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/ips/pools/{pool_name}": { - "delete": { + "/partner_settings/new_relic": { + "parameters": [], + "patch": { + "description": "**This endpoint allows you to update or change your 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": "Updates New Relic partner settings.", "consumes": [ "application/json" ], - "description": "", - "operationId": "Delete an IP pool.", - "parameters": [], - "produces": [], + "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." + } + } + } + } + ], "responses": { - "204": { + "200": { "description": "", "schema": { - "properties": {}, - "type": "object" + "$ref": "#/definitions/partner_settings_new_relic" + }, + "examples": { + "application/json": { + "enable_subuser_statistics": true, + "enabled": true, + "license_key": "" + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, "get": { + "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": "Returns all New Relic partner settings.", "consumes": [ "application/json" ], - "description": "", - "operationId": "List the IPs in a specified pool.", - "parameters": [], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", "schema": { - "properties": { - "ips": { - "items": { - "type": "string" - }, - "type": "array" - }, - "pool_name": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/partner_settings_new_relic" + }, + "examples": { + "application/json": { + "enable_subuser_statistics": false, + "enabled": true, + "license_key": "" + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "pool_name", - "required": true, - "type": "string" - } - ], - "put": { + ] + } + }, + "/partner_settings": { + "parameters": [], + "get": { + "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": "Returns a list of all partner settings.", "consumes": [ "application/json" ], - "description": "", - "operationId": "Update an IP pool\u2019s name.", - "parameters": [], - "produces": [], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "The number of settings to return per page.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The paging offset.", + "type": "integer" + } + ], "responses": { - "default": { + "200": { "description": "", - "schema": {} + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The title of the partner." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this partner setting has been enabled." + }, + "name": { + "type": "string", + "description": "The name of the partner setting." + }, + "description": { + "type": "string", + "description": "A description of this partner setting." + } + }, + "required": [ + "title", + "enabled", + "name", + "description" + ] + } + } + } + }, + "examples": { + "application/json": { + "result": [ + { + "title": "Partner title", + "enabled": true, + "name": "partner_name", + "description": "A description of a partner." + } + ] + } + } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/ips/pools/{pool_name}/ips": { - "parameters": [ - { - "in": "path", - "name": "pool_name", - "required": true, - "type": "string" - } - ], - "post": { + "/mail_settings/spam_check": { + "parameters": [], + "patch": { + "description": "", + "operationId": "Update spam check mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Assign an IP to a pool", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "ip": { + "enabled": { + "type": "boolean" + }, + "url": { "type": "string" + }, + "max_score": { + "type": "integer" } - }, - "type": "object" + } } } ], - "produces": [], - "responses": { - "default": { - "description": "", - "schema": {} - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/ips/pools/{pool_name}/ips/{ip}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Remove an IP address from a pool.", - "parameters": [], - "produces": [], "responses": { - "default": { + "200": { "description": "", - "schema": {} + "schema": { + "$ref": "#/definitions/mail_settings_spam_check" + }, + "examples": { + "application/json": { + "enabled": false, + "max_score": 6, + "url": "http://example.com" + } + } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [ - { - "in": "path", - "name": "pool_name", - "required": true, - "type": "string" - }, - { - "in": "path", - "name": "ip", - "required": true, - "type": "string" - } - ] - }, - "/ips/warmup": { "get": { + "description": "", + "operationId": "Get spam check mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get all IPs that are currently warming up.", + "produces": [ + "application/json" + ], "parameters": [], - "produces": [], "responses": { - "default": { + "200": { "description": "", - "schema": {} + "schema": { + "$ref": "#/definitions/mail_settings_spam_check" + }, + "examples": { + "application/json": { + "enabled": false, + "max_score": 6, + "url": "http://example.com" + } + } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/mail_settings/forward_spam": { "parameters": [], - "post": { + "patch": { + "description": "", + "operationId": "Update forward spam mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Add an IP to warmup.", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { - "properties": { - "ip": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/mail_settings_forward_spam" } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - }, "schema": { - "items": { - "properties": { - "ip": { - "type": "string" - }, - "start_date": { - "type": "integer" - } - }, - "type": "object" - }, - "type": "array" + "$ref": "#/definitions/mail_settings_forward_spam" + }, + "examples": { + "application/json": { + "email": "", + "enabled": false + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - } - }, - "/ips/warmup/{ip_address}": { - "delete": { + ] + }, + "get": { + "description": "", + "operationId": "Get forward spam mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Remove an IP from warmup.", + "produces": [ + "application/json" + ], "parameters": [], - "produces": [], "responses": { - "204": { + "200": { "description": "", "schema": { - "properties": {}, - "type": "object" + "$ref": "#/definitions/mail_settings_forward_spam" + }, + "examples": { + "application/json": { + "email": "", + "enabled": true + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "get": { + ] + } + }, + "/mail_settings/forward_bounce": { + "parameters": [], + "patch": { + "description": "", + "operationId": "Update forward bounce mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get warmup status for a particular IP.", - "parameters": [], - "produces": [], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "email": { + "type": "string" + } + } + } + } + ], "responses": { - "default": { + "200": { "description": "", - "schema": {} + "schema": { + "$ref": "#/definitions/mail_settings_forward_bounce" + }, + "examples": { + "application/json": { + "email": "", + "enabled": true + } + } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "ip_address", - "required": true, - "type": "string" - } - ] - }, - "/ips/{ip_address}": { + ] + }, "get": { + "description": "", + "operationId": "Get forward bounce mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "See which pools an IP address belongs to.", + "produces": [ + "application/json" + ], "parameters": [], - "produces": [], "responses": { - "default": { + "200": { "description": "", - "schema": {} + "schema": { + "$ref": "#/definitions/mail_settings_forward_bounce" + }, + "examples": { + "application/json": { + "enabled": false, + "email": null + } + } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "ip_address", - "required": true, - "type": "string" - } - ] + ] + } }, - "/mail/batch": { + "/categories": { "parameters": [], - "post": { + "get": { + "description": "", + "operationId": "Get categories", "consumes": [ "application/json" ], - "description": "Generate a new Batch ID to associate 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": "Create a batch ID", - "parameters": [], "produces": [ "application/json" ], + "parameters": [ + { + "name": "limit", + "in": "query", + "type": "integer" + }, + { + "name": "sort_by", + "in": "query", + "type": "string" + }, + { + "name": "order", + "in": "query", + "type": "string" + }, + { + "name": "category", + "in": "query", + "type": "string" + }, + { + "name": "offset", + "in": "query", + "type": "integer" + } + ], "responses": { - "201": { + "200": { "description": "", - "examples": { - "application/json": { - "batch_id": "YOUR_BATCH_ID" - } - }, "schema": { - "properties": { - "batch_id": { - "pattern": "^[a-zA-Z0-9\\-\\_]", - "type": "string" - } - }, - "required": [ - "batch_id" - ], - "title": "Generate Batch ID response", - "type": "object" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "array", + "items": { + "type": "object", + "properties": { + "category": { + "type": "string" } - ] + } } }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "examples": { + "application/json": [ + { + "category": "category 1" + }, + { + "category": "category 2" + } + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Generate a new Batch ID to associate with scheduled sends" + ] } }, - "/mail/batch/{batch_id}": { + "/user/account": { + "parameters": [], "get": { + "description": "Your user's account information includes the user's account type and reputation.", + "operationId": "Get a user's account information.", "consumes": [ "application/json" ], - "description": "Validate whether or not a batch id is valid.\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": "Validate batch ID", - "parameters": [ - { - "description": "The ID you can use to associate multiple scheduled sends together, in case you might want to cancel or pause those sends.", - "in": "query", - "name": "batch_id", - "pattern": "^[A-Za-z0-9]", - "required": true, - "type": "string" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - } - }, "schema": { - "$ref": "#/definitions/mail_batch_id" - } - }, - "400": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "invalid batch id" - } - ] - } + "title": "GET User Account response", + "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" + ] }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "Unexpected error in API call. See HTTP response body for details.", "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "reputation": 100, + "type": "paid" } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Validate whether or not a batch id is valid" - }, - "parameters": [ - { - "in": "path", - "name": "batch_id", - "required": true, - "type": "string" - } - ] + ] + } }, "/mail_settings": { + "parameters": [], "get": { + "description": "", + "operationId": "Get all mail settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get all mail settings", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", "name": "limit", - "type": "string" + "in": "query", + "type": "integer" }, { - "in": "query", "name": "offset", - "type": "string" + "in": "query", + "type": "integer" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + } + } + } + } + } + }, "examples": { "application/json": { "result": [ { - "description": "Address / domains that should never have email suppressed.", + "title": "Address Whitelist", "enabled": false, "name": "address_whitelist", - "title": "Address Whitelist" + "description": "Address / domains that should never have email suppressed." }, { - "description": "Automatically BCC an address for every e-mail sent.", + "title": "BCC", "enabled": false, "name": "bcc", - "title": "BCC" + "description": "Automatically BCC an address for every e-mail sent." }, { - "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days.", + "title": "Bounce Purge", "enabled": false, "name": "bounce_purge", - "title": "Bounce Purge" + "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days." }, { - "description": "Controls notifications for events, such as bounces, clicks, and opens.", + "title": "Event Notification", "enabled": true, "name": "event_notify", - "title": "Event Notification" + "description": "Controls notifications for events, such as bounces, clicks, and opens." }, { - "description": "Allows you to add a custom footer to outgoing email.", + "title": "Footer", "enabled": false, "name": "footer", - "title": "Footer" + "description": "Allows you to add a custom footer to outgoing email." }, { - "description": "Allows you to forward bounces to a specific email address.", + "title": "Forward Bounce", "enabled": true, "name": "forward_bounce", - "title": "Forward Bounce" + "description": "Allows you to forward bounces to a specific email address." }, { - "description": "Allows for a copy of spam reports to be forwarded to an email address.", + "title": "Forward Spam", "enabled": false, "name": "forward_spam", - "title": "Forward Spam" + "description": "Allows for a copy of spam reports to be forwarded to an email address." }, { - "description": "Allows you to customize your outgoing HTML emails.", + "title": "Legacy Email Template", "enabled": true, "name": "template", - "title": "Legacy Email Template" + "description": "Allows you to customize your outgoing HTML emails." }, { - "description": "Convert your plain text emails to HTML.", + "title": "Plain Content", "enabled": false, "name": "plain_content", - "title": "Plain Content" + "description": "Convert your plain text emails to HTML." }, { - "description": "Check outbound messages for spam content.", + "title": "Spam Checker", "enabled": true, - "name": "spam_check", - "title": "Spam Checker" - } - ] - } - }, - "schema": { - "properties": { - "result": { - "items": { - "properties": { - "description": { - "type": "string" - }, - "enabled": { - "type": "boolean" - }, - "name": { - "type": "string" - }, - "title": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - } - }, - "type": "object" + "name": "spam_check", + "description": "Check outbound messages for spam content." + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [] + ] + } }, - "/mail_settings/address_whitelist": { + "/whitelabel/ips": { + "parameters": [], "get": { + "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": "Retrieve all IP whitelabels", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get address whitelist mail settings", - "parameters": [], "produces": [ "application/json" ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "The number of results to retrieve.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list of results to begin retrieving IPs from.", + "type": "integer" + }, + { + "name": "ip", + "in": "query", + "description": "The IP segment that you would like to use in a prefix search.", + "type": "string" + } + ], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "enabled": false, - "list": [ - "example.com" - ] + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/ip_whitelabel" } }, - "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" + "examples": { + "application/json": [ + { + "id": 1, + "ip": "192.168.1.1", + "rdns": "o1.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 + }, + { + "username": "jane@example.com", + "user_id": 8 + } + ], + "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" + } + }, + { + "id": 2, + "ip": "192.168.1.2", + "rdns": "o2.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 + }, + { + "username": "jane@example2.com", + "user_id": 9 + } + ], + "subdomain": "email", + "domain": "example.com", + "valid": true, + "legacy": false, + "a_record": { + "valid": true, + "type": "a", + "host": "o2.email.example.com", + "data": "192.168.1.2" + } + } + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [], - "patch": { + "post": { + "description": "**This endpoint allows you to create an IP whitelabel.**\n\nWhen creating an IP whitelable, you should use the same subdomain that you used when you created a domain 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": "Create an IP whitelabel", "consumes": [ "application/json" ], - "description": "", - "operationId": "Update address whitelist mail settings", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "enabled": { - "type": "boolean" + "ip": { + "type": "string", + "description": "The IP address that you want to whitelabel." }, - "list": { - "items": { - "type": "string" - }, - "type": "array" + "subdomain": { + "type": "string", + "description": "The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel." + }, + "domain": { + "type": "string", + "description": "The root, or sending, domain that will be used to send message from the IP." } }, - "type": "object" + "required": [ + "ip", + "subdomain", + "domain" + ] } } ], - "produces": [ - "application/json" - ], "responses": { - "200": { + "201": { "description": "", + "schema": { + "$ref": "#/definitions/ip_whitelabel" + }, "examples": { "application/json": { - "enabled": false, - "list": [ - "example.com" - ] + "id": 123, + "ip": "192.168.1.2", + "rdns": "o1.email.example.com", + "users": [], + "subdomain": "email", + "domain": "example.com", + "valid": true, + "legacy": false, + "a_record": { + "valid": true, + "type": "a", + "host": "o1.email.example.com", + "data": "192.168.1.2" + } } - }, - "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/mail_settings/bcc": { + "/contactdb/segments/{segment_id}/recipients": { + "parameters": [ + { + "name": "segment_id", + "in": "path", + "required": true, + "type": "integer" + } + ], "get": { + "description": "List all of the recipients in a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", + "operationId": "List Recipients On a Segment", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get BCC mail settings", - "parameters": [], "produces": [ "application/json" ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "email": "example@example.com", - "enabled": false - } - }, - "schema": { - "$ref": "#/definitions/mail_settings_bcc" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "patch": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Update BCC mail settings", "parameters": [ { - "in": "body", - "name": "body", - "schema": { - "$ref": "#/definitions/mail_settings::patch" - } + "name": "page", + "in": "query", + "type": "integer" + }, + { + "name": "page_size", + "in": "query", + "type": "integer" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "email": "example@example.com", - "enabled": false - } - }, "schema": { + "title": "List Recipients On a Segment response", + "type": "object", "properties": { - "email": { - "type": "string" - }, - "enabled": { - "type": "boolean" + "recipients": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_recipient" + } } }, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/mail_settings/bounce_purge": { - "get": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Get bounce purge mail settings", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { + "required": [ + "recipients" + ] + }, + "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\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"" + }, + "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { - "enabled": false, - "hard_bounces": null, - "soft_bounces": 1234 + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } - }, - "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" } + }, + "404": { + "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"" } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/suppression/bounces": { "parameters": [], - "patch": { + "delete": { + "description": "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete 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)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes.", + "operationId": "Delete bounces", "consumes": [ "application/json" ], - "description": "", - "operationId": "Update bounce purge mail settings", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "enabled": { - "type": "boolean" - }, - "hard_bounces": { - "type": "integer" + "delete_all": { + "type": "boolean", + "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter." }, - "soft_bounces": { - "type": "integer" + "emails": { + "type": "array", + "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", + "items": { + "type": "string" + } } - }, - "type": "object" + } } } ], - "produces": [ - "application/json" - ], "responses": { - "200": { + "204": { "description": "", - "examples": { - "application/json": { - "enabled": false, - "hard_bounces": null, - "soft_bounces": null - } - }, "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" + "type": "null" } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/mail_settings/footer": { - "get": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Get footer mail settings [params can be null?]", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { + }, + "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } - }, - "schema": { - "$ref": "#/definitions/mail_settings_footer" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [], - "patch": { + "get": { + "description": "Bounces 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": "List all bounces", "consumes": [ "application/json" ], - "description": "", - "operationId": "Update footer mail settings", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", - "name": "body", - "schema": { - "$ref": "#/definitions/mail_settings::patch" - } + "name": "start_time", + "in": "query", + "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", + "type": "number" + }, + { + "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" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "number" + }, + "email": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "status": { + "type": "string" + } + } } }, + "examples": { + "application/json": [ + { + "created": 1250337600, + "email": "example@example.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" + }, + { + "created": 1250337600, + "email": "example@example.com", + "reason": "550 5.1.1Check out our spring line!
", + "plain_content": "Check out our spring line!", + "status": "Draft" } - }, + } + }, + "401": { + "description": "", "schema": { - "$ref": "#/definitions/mail_settings_spam_check" + "type": "object", + "properties": {} + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"\": \"not found\"", + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [], "patch": { + "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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Update a Campaign", "consumes": [ "application/json" ], - "description": "", - "operationId": "Update spam check mail settings", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "title": "Update a Campaign request", + "type": "object", "properties": { - "enabled": { - "type": "boolean" + "title": { + "type": "string", + "description": "The title of the campaign." }, - "max_score": { - "type": "integer" + "subject": { + "type": "string", + "description": "The subject line for your campaign." }, - "url": { - "type": "string" + "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." } }, - "type": "object" + "required": [ + "title", + "subject", + "categories", + "html_content", + "plain_content" + ] } } ], - "produces": [ - "application/json" - ], "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\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", + "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": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "403": { + "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", + "schema": { + "type": "object", + "properties": {} + }, + "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" + } + ] } - }, - "schema": { - "$ref": "#/definitions/mail_settings_spam_check" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/mail_settings/template": { - "get": { + "/asm/suppressions/global": { + "parameters": [], + "post": { + "description": "Global Suppressions are email addresses that will not receive any emails.", + "operationId": "Add recipient addresses to the global suppression group.", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get template mail settings", - "parameters": [], "produces": [ "application/json" ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "enabled": false, - "html_content": "<% body %>Example
\n" - } - }, - "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - }, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "patch": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Update template mail settings", "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" + "recipient_emails": { + "type": "array", + "items": { + "type": "string" + } } - }, - "type": "object" + } } } ], - "produces": [ - "application/json" - ], "responses": { - "200": { + "201": { "description": "", - "examples": { - "application/json": { - "enabled": false, - "html_content": "<% body %>Example
\n" - } - }, "schema": { + "type": "object", "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" + "recipient_emails": { + "type": "array", + "items": { + "type": "string" + } } - }, - "type": "object" + } + }, + "examples": { + "application/json": { + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/mailbox_providers/stats": { + "/tracking_settings/subscription": { + "parameters": [], "get": { + "description": "", + "operationId": "Get Subscription Tracking Settings", "consumes": [ "application/json" ], - "description": "", - "operationId": "Gets email statistics by mailbox provider.", - "parameters": [ - { - "in": "query", - "name": "limit", - "type": "string" - }, - { - "in": "query", - "name": "offset", - "type": "string" - }, - { - "in": "query", - "name": "aggregated_by", - "type": "string" - }, - { - "in": "query", - "name": "start_date", - "type": "string" - }, - { - "in": "query", - "name": "end_date", - "type": "string" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "date": "2015-10-17", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "html_content": { + "type": "string" }, - { - "date": "2015-10-18", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "landing": { + "type": "string" }, - { - "date": "2015-10-19", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "plain_content": { + "type": "string" }, - { - "date": "2015-10-20", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "replace": { + "type": "string" }, - { - "date": "2015-10-21", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 1, - "drops": 0, - "opens": 1, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "url": { + "type": "string" + } + } + }, + "examples": { + "application/json": { + "enabled": true, + "html_content": "Something something unsubscribe <% %> something something
\n", + "landing": "subscribehere
\n", + "plain_content": "Something something unsubscribe <% %> something something", + "replace": "thetag", + "url": "" + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "description": "", + "operationId": "Update Subscription Tracking Settings", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "date": "2015-10-22", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "landing": { + "type": "string" }, - { - "date": "2015-10-23", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "url": { + "type": "string" }, - { - "date": "2015-10-24", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "replace": { + "type": "string" }, - { - "date": "2015-10-25", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "html_content": { + "type": "string" }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 2, - "drops": 0, - "opens": 2, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 2 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "plain_content": { + "type": "string" + } + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "landing": { + "type": "string" }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "url": { + "type": "string" }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "replace": { + "type": "string" }, - { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "html_content": { + "type": "string" + }, + "plain_content": { + "type": "string" + } + } + }, + "examples": { + "application/json": { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail/batch/{batch_id}": { + "parameters": [ + { + "name": "batch_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "description": "Validate whether or not a batch id is valid.\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": "Validate batch ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_batch_id" + }, + "examples": { + "application/json": { + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" + } + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "invalid batch id" + } + ] + } + } + }, + "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" + } + ] + } + } + } + }, + "summary": "Validate whether or not a batch id is valid", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/profile": { + "parameters": [], + "patch": { + "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)\n\nIt 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": "Update a user's profile", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/user_profile" + } + }, + { + "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" + } + ], + "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" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "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 a user's profile", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "title": "GET User Profile response", + "type": "object", + "properties": { + "address": { + "type": "string", + "description": "The user's address." }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "address2": { + "type": "string", + "description": "The second line of the user's address." }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "city": { + "type": "string", + "description": "The user's city." }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "company": { + "type": "string", + "description": "The name of the user's company." }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "country": { + "type": "string", + "description": "The user's country." }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "first_name": { + "type": "string", + "description": "The user's first name." }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "last_name": { + "type": "string", + "description": "The user's last name." }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "phone": { + "type": "string", + "description": "The user's phone number." }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" + "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": [ + "address", + "city", + "company", + "country", + "first_name", + "last_name", + "phone", + "state", + "website", + "zip" + ] + }, + "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": "", + "schema": { + "type": "object", + "properties": {} + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns/{campaign_id}/schedules/test": { + "parameters": [ + { + "name": "campaign_id", + "in": "path", + "required": true, + "type": "integer" + } + ], + "post": { + "description": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Send a Test Campaign", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "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" + ] + } + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "title": "Send a Test Campaign request", + "type": "object", + "properties": { + "to": { + "type": "string" + } + }, + "required": [ + "to" + ] + } + }, + "400": { + "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"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" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "summary": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/ips": { + "parameters": [], + "get": { + "description": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabel info.\nThe start_date field corresponds to when warmup started for that IP.", + "operationId": "List all IPs", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "ip", + "in": "query", + "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": "The number of IPs you want returned at the same time.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The offset for the number of IPs that you are requesting.", + "type": "integer" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "subusers": { + "type": "array", + "items": { + "type": "string" } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" + }, + "rdns": { + "type": "string" + }, + "pools": { + "type": "array", + "items": { + "type": "string" } - ] - }, + }, + "warmup": { + "type": "boolean" + }, + "start_date": { + "type": [ + "number", + "null" + ] + }, + "whitelabeled": { + "type": "boolean" + } + } + } + }, + "examples": { + "application/json": [ { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "ip": "127.0.0.1", + "subusers": [ + "example_subuser1", + "example_subuser2" + ], + "rdns": "o1.em.example.com", + "pools": [], + "warmup": true, + "start_date": 1250337600, + "whitelabeled": true }, { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "mailbox_provider" - } - ] + "ip": "127.0.0.1", + "subusers": [], + "pools": [], + "warmup": false, + "start_date": null, + "whitelabeled": false } ] - }, + } + } + }, + "summary": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabe", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/whitelabel/links/default": { + "parameters": [], + "get": { + "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:\nCheck out our spring line!
", + "plain_content": "Check out our spring line!", + "status": "Draft" }, - "stats": { - "items": { - "properties": { - "metrics": { - "properties": { - "blocks": { - "type": "number" - }, - "bounce_drops": { - "type": "number" - }, - "bounces": { - "type": "number" - }, - "clicks": { - "type": "number" - }, - "deferred": { - "type": "number" - }, - "delivered": { - "type": "number" - }, - "invalid_emails": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "processed": { - "type": "number" - }, - "requests": { - "type": "number" - }, - "spam_report_drops": { - "type": "number" - }, - "spam_reports": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - }, - "unsubscribe_drops": { - "type": "number" - }, - "unsubscribes": { - "type": "number" - } - }, - "type": "object" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - }, - "type": "array" + { + "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" } - }, - "type": "object" - }, - "type": "array" + ] + } } } }, + "summary": "Returns campaigns in reverse order they were created (newest first)\nReturns an empty array if no campaigns exist", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [] - }, - "/subusers/stats/sums": { - "get": { + "post": { + "description": "Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\n\nNote: 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.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", + "operationId": "Create a Campaign", "consumes": [ "application/json" ], - "description": "", - "operationId": " Gets the total sums of each email statistic metric for all subusers over the given date range.", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", - "name": "sort_by_direction", - "type": "string" - }, - { - "in": "query", - "name": "start_date", - "type": "string" - }, - { - "in": "query", - "name": "end_date", - "type": "string" + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/campaign_request" + } + } + ], + "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" + } + } }, - { - "in": "query", - "name": "limit", - "type": "string" + "400": { + "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"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", + "properties": {} + } + } + }, + "summary": "{% info %}\nA campaign requires a title to be created.\nIn order to send or schedule the campaign, you will be required to", + "security": [ { - "in": "query", - "name": "offset", - "type": "string" - }, + "Authorization": [] + } + ] + } + }, + "/subusers/reputations": { + "parameters": [], + "get": { + "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": "Retrieve Subuser Reputations", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ { + "name": "usernames", "in": "query", - "name": "aggregated_by", "type": "string" + } + ], + "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" + ] + } + }, + "examples": { + "application/json": [ + { + "username": "example_subuser", + "reputation": 99 + }, + { + "username": "example_subuser2", + "reputation": 95.2 + } + ] + } }, + "401": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + } + }, + "summary": "", + "security": [ { - "in": "query", - "name": "sort_by_metric", - "type": "string" + "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": { + "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": "Retrieve an IP whitelabel", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", + "schema": { + "$ref": "#/definitions/ip_whitelabel" + }, "examples": { "application/json": { - "date": "2015-10-11", - "stats": [] + "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": { - "date": { - "type": "string" - }, - "stats": { + "errors": { + "type": "array", + "description": "The errors preventing the retrieval of the IP whitelabel.", "items": { - "properties": {} - }, - "type": "array" + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message explaining why the IP whitelabel could not be found." + } + }, + "required": [ + "message" + ] + } } }, - "type": "object" + "required": [ + "errors" + ] + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] }, - "parameters": [] - }, - "/subusers/{subuser_name}": { "delete": { + "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 an IP whitelabel", "consumes": [ "application/json" ], - "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 a subuser", - "parameters": [ - { - "description": "The name of the subuser.", - "in": "query", - "name": "subuser_name", - "required": true, - "type": "string" - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { "204": { "description": "", "schema": { - "properties": {}, - "type": "object" + "type": "object", + "properties": {} } }, - "401": { + "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": [ { - "field": null, - "message": "authorization required" + "message": "Whitelabel ip not found." } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "subuser_name", - "required": true, - "type": "string" - } - ], + ] + } + }, + "/mail_settings/bounce_purge": { + "parameters": [], "patch": { + "description": "", + "operationId": "Update bounce purge mail settings", "consumes": [ "application/json" ], - "description": "This endpoint allows you to enable or disable a subuser.\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": "Enable/disable a subuser", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "disabled": { - "description": "Whether or not this subuser is disabled. True means disabled, False means enabled.", + "enabled": { "type": "boolean" + }, + "hard_bounces": { + "type": "integer" + }, + "soft_bounces": { + "type": "integer" + } + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_settings_bounce_purge" + }, + "examples": { + "application/json": { + "enabled": false, + "hard_bounces": null, + "soft_bounces": null + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "description": "", + "operationId": "Get bounce purge mail settings", + "consumes": [ + "application/json" + ], + "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 + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/whitelabel/links": { + "parameters": [], + "post": { + "description": "**This endpoint allows you to create a new 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": "Create a Link Whitelabel", + "consumes": [ + "application/json" + ], + "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": "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" + ] + } + } + ], + "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" + } } - }, - "type": "object" + } } } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "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": "Retrieve all link whitelabels", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "Limits the number of results returned per page.", + "type": "integer" + } + ], "responses": { - "204": { + "200": { "description": "", "schema": { - "properties": {}, - "type": "object" - } - }, - "400": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid username" - }, - { - "message": "no fields provided" - } - ] + "type": "array", + "items": { + "$ref": "#/definitions/link_whitelabel" } }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "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" + } } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "500": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "message": "unable to enable user" + }, + { + "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" + } } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + } + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/subusers/{subuser_name}/ips": { - "parameters": [ - { - "in": "path", - "name": "subuser_name", - "required": true, - "type": "string" - } - ], - "put": { + "/user/settings/enforced_tls": { + "parameters": [], + "patch": { + "description": "", + "operationId": "Change the Enforced TLS settings", "consumes": [ "application/json" ], - "description": "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)", - "operationId": "Update IPs assigned to a subuser", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", - "name": "subuser_name", - "required": true, - "type": "string" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + } + } } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "ips": [ - "127.0.0.1" - ] - } - }, "schema": { + "type": "object", "properties": { - "ips": { - "items": { - "format": "ipv4", - "type": "string" - }, - "type": "array" + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" } - }, - "type": "object" - } - }, - "401": { - "description": "", + } + }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "require_tls": true, + "require_valid_cert": false } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, - "summary": "" - } - }, - "/subusers/{subuser_name}/monitor": { - "delete": { - "consumes": [ - "application/json" - ], - "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 monitor settings", - "parameters": [ + "summary": "", + "security": [ { - "description": "The name of the subuser from whom you would like to delete the monitor settings. ", - "in": "query", - "name": "subuser_name", - "required": true, - "type": "string" + "Authorization": [] } + ] + }, + "get": { + "description": "", + "operationId": "Get the current Enforced TLS settings.", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "204": { + "200": { "description": "", "schema": { - "properties": {}, - "type": "object" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "type": "object", + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } } }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "", "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] + "require_tls": false, + "require_valid_cert": false } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } - }, - "summary": "" - }, - "get": { - "consumes": [ - "application/json" - ], - "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": "Retrieve monitor settings for a subuser", - "parameters": [ + }, + "summary": "", + "security": [ { - "description": "The name of the subuser for which to retrieve monitor settings.", - "in": "query", - "name": "subuser_name", - "type": "string" + "Authorization": [] } + ] + } + }, + "/mail/batch": { + "parameters": [], + "post": { + "description": "Generate a new Batch ID to associate 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": "Create a batch ID", + "consumes": [ + "application/json" ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "200": { + "201": { "description": "", + "schema": { + "$ref": "#/definitions/mail_batch_id" + }, "examples": { "application/json": { - "email": "example@example.com", - "frequency": 500 + "batch_id": "YOUR_BATCH_ID" } - }, - "schema": { - "$ref": "#/definitions/monitor" } }, "401": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, "schema": { "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "", + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "No monitor settings for this user" + "message": "authorization required" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "Generate a new Batch ID to associate with scheduled sends", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/subusers/{subuser_name}/ips": { "parameters": [ { - "in": "path", "name": "subuser_name", + "in": "path", "required": true, "type": "string" } ], - "post": { + "put": { + "description": "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)", + "operationId": "Update IPs assigned to a subuser", "consumes": [ "application/json" ], - "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": "Create monitor settings", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "$ref": "#/definitions/monitor" - } - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", + "schema": { + "type": "object", + "properties": { + "ips": { + "type": "array", + "items": { + "type": "string", + "format": "ipv4" + } + } + } + }, "examples": { "application/json": { - "email": "example@example.com", - "frequency": 50000 + "ips": [ + "127.0.0.1" + ] } - }, - "schema": { - "$ref": "#/definitions/monitor" } }, - "400": { + "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { "errors": [ { "field": null, - "message": "User already has a monitor" + "message": "authorization required" } ] } - }, + } + } + }, + "summary": "" + } + }, + "/api_keys": { + "parameters": [], + "get": { + "description": "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": "List all API Keys belonging to the authenticated user", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "result": { + "type": "array", + "_isOpen": true, + "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": [ @@ -12310,5004 +11576,6703 @@ } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "**List all API Keys belonging to the authenticated user**\n\nThe API Keys feature allows customers to be able to generate ", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "put": { + ] + } + }, + "/whitelabel/domains/{id}/validate": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "post": { + "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 “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.\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": "Validate a domain whitelabel.", "consumes": [ "application/json" ], - "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": "Update Monitor Settings for a subuser", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "$ref": "#/definitions/monitor" - } - } - ], "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": { - "email": "example@example.com", - "frequency": 500 + "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 + } + } } - }, - "schema": { - "$ref": "#/definitions/monitor" } }, "400": { + "description": "Unexpected error in API call. See HTTP response body for details.", + "schema": { + "type": "object", + "properties": {} + } + }, + "500": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": "email", - "message": "Email is required" + "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" + ] } - ] + } } }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", "examples": { "application/json": { "errors": [ { - "field": null, - "message": "authorization required" + "message": "internal error getting TXT" } ] } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/suppression/bounces": { - "delete": { + "/devices/stats": { + "parameters": [], + "get": { + "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": "Retrieve email statistics by device type.", "consumes": [ "application/json" ], - "description": "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete 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)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes.", - "operationId": "Delete bounces", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", - "name": "body", + "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.", + "required": false, + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "How many results to exclude.", + "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" + }, + { + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics to retrieve.", + "required": true, + "type": "string" + } + ], + "responses": { + "200": { + "description": "", "schema": { - "properties": { - "delete_all": { - "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter.", - "type": "boolean" + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_opens" + } + }, + "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 + } + } + ] }, - "emails": { - "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "type": "object" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "get": { - "consumes": [ - "application/json" - ], - "description": "Bounces 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": "List all bounces", - "parameters": [ - { - "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", - "in": "query", - "name": "start_time", - "type": "number" - }, - { - "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" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": [ { - "created": 1250337600, - "email": "example@example.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" + "date": "2015-10-27", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] }, { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1Something something unsubscribe <% %> something something
\n", - "landing": "subscribehere
\n", - "plain_content": "Something something unsubscribe <% %> something something", - "replace": "thetag", - "url": "" - } - }, - "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "url": { - "type": "string" - } - }, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "patch": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Update Subscription Tracking Settings", - "parameters": [ - { - "in": "body", - "name": "body", "schema": { + "title": "Send a Campaign response", + "type": "object", "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" + "id": { + "type": "integer", + "format": "int64" }, - "url": { + "status": { "type": "string" } }, - "type": "object" + "required": [ + "id", + "status" + ] + }, + "examples": { + "application/json": { + "id": 1234, + "status": "Scheduled" + } } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", + }, + "400": { + "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", "schema": { - "type": "object" + "$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" + } + ] + } } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/user/account": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Your user's account information includes the user's account type and reputation.", - "operationId": "Get a user's account information.", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { + }, + "401": { "description": "", + "schema": { + "$ref": "#/definitions/global:ErrorResponse" + }, "examples": { "application/json": { - "reputation": 100, - "type": "paid" + "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": { - "properties": { - "reputation": { - "description": "The sender reputation for this user.", - "type": "number" - }, - "type": { - "description": "The type of account for this user.", - "enum": [ - "free", - "paid" - ], - "type": "string" - } - }, - "required": [ - "type", - "reputation" - ], - "title": "GET User Account response", - "type": "object" + "$ref": "#/definitions/global:ErrorResponse" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [] + ] + } }, - "/user/profile": { + "/user/webhooks/parse/stats": { + "parameters": [], "get": { + "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": "Retrieves Inbound Parse Webhook statistics.", "consumes": [ "application/json" ], - "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 a user's profile", - "parameters": [], "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" + } + ], "responses": { "200": { "description": "", - "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" + "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" + ] } }, - "schema": { - "properties": { - "address": { - "description": "The user's address.", - "type": "string" + "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 + } + } + ] }, - "address2": { - "description": "The second line of the user's address.", - "type": "string" + { + "date": "2015-10-20", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "city": { - "description": "The user's city.", - "type": "string" + { + "date": "2015-10-21", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "company": { - "description": "The name of the user's company.", - "type": "string" + { + "date": "2015-10-22", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "country": { - "description": "The user's country.", - "type": "string" + { + "date": "2015-10-23", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "first_name": { - "description": "The user's first name.", - "type": "string" + { + "date": "2015-10-24", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "last_name": { - "description": "The user's last name.", - "type": "string" + { + "date": "2015-10-25", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "phone": { - "description": "The user's phone number.", - "type": "string" + { + "date": "2015-10-26", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "state": { - "description": "The user's state.", - "type": "string" + { + "date": "2015-10-27", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "website": { - "description": "The user's website URL.", - "type": "string" + { + "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 + } + } + ] }, - "zip": { - "description": "The user's zip code.", - "type": "string" - } - }, - "required": [ - "address", - "city", - "company", - "country", - "first_name", - "last_name", - "phone", - "state", - "website", - "zip" - ], - "title": "GET User Profile response", - "type": "object" - } - }, - "401": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "patch": { - "consumes": [ - "application/json" - ], - "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)\n\nIt 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": "Update a user's profile", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "$ref": "#/definitions/user_profile" - } - }, - { - "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": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "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" - } - }, - "schema": { - "$ref": "#/definitions/user_profile" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/user/scheduled_sends": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Get 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 all scheduled sends", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": [ { - "batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg", - "status": "cancel" + "date": "2015-11-02", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, { - "batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2", - "status": "cancel" - } - ] - }, - "schema": { - "items": { - "$ref": "#/definitions/user_scheduled_send_status" - }, - "type": "array" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "post": { - "consumes": [ - "application/json" - ], - "description": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.\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": "Cancel or pause a scheduled send", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "properties": { - "batch_id": { - "description": "The batch ID is the identifier that your scheduled mail sends share.", - "pattern": "^[a-zA-Z0-9]", - "type": "string" + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] }, - "status": { - "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" - ], - "type": "string" - } - }, - "required": [ - "batch_id", - "status" - ], - "title": "Cancel or pause a scheduled send request", - "type": "object" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/user_scheduled_send_status" - } - }, - "400": { - "description": "\"\" : \"max limit reached\"\n\"batch_id\" : \"invalid batch id\"\n\"batch_id\" : \"a status for this batch id exists, try PATCH to update the status\"", - "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" - } - ] - } - }, - "schema": { - "properties": {}, - "type": "object" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "properties": {}, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned." - } - }, - "/user/scheduled_sends/{batch_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "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 a cancellation or pause of a scheduled send", - "parameters": [ - { - "description": "The batch ID with the cancel or pause that you would like to delete.", - "in": "query", - "name": "batch_id", - "pattern": "^[a-zA-Z0-9]", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + { + "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 + } + } + ] + } + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Delete the cancellation/pause of a scheduled send." - }, + ] + } + }, + "/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": { + "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": "Retrieve stats by a specific client type.", "consumes": [ "application/json" ], - "description": "Get 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": "Retrieve scheduled send", + "produces": [ + "application/json" + ], "parameters": [ { - "description": "The batch ID is the identifier that your scheduled mail sends share.\t", + "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", - "name": "batch_id", - "pattern": "^[a-zA-Z0-9]", + "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" + ] } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_opens" + } + }, "examples": { "application/json": [ { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", - "status": "cancel" + "date": "2014-10-01", + "stats": [ + { + "metrics": { + "opens": 1, + "unique_opens": 1 + }, + "name": "Gmail", + "type": "client" + } + ] }, { - "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", - "status": "pause" + "date": "2014-10-02", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Gmail", + "type": "client" + } + ] } ] - }, - "schema": { - "items": { - "$ref": "#/definitions/user_scheduled_send_status" - }, - "title": "Retrieve scheduled send response", - "type": "array" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" } } }, + "summary": "Gets email statistics by a single client type.", "security": [ { "Authorization": [] } - ], - "summary": "Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations\na" - }, - "parameters": [ - { - "in": "path", - "name": "batch_id", - "required": true, - "type": "string" - } - ], - "patch": { + ] + } + }, + "/browsers/stats": { + "parameters": [], + "get": { + "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": "Retrieve email statistics by browser. ", "consumes": [ "application/json" ], - "description": "Update the status 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": "Update user scheduled send information", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", - "name": "body", - "schema": { - "properties": { - "status": { - "description": "The status you would like the scheduled send to have.", - "enum": [ - "cancel", - "pause" - ], - "type": "string" - } - }, - "required": [ - "status" - ], - "type": "object" - } + "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" } ], - "produces": [ - "application/json" - ], "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { + "200": { "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": "status", - "message": "status must be either cancel or pause" - } - ] - } - }, "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "401": { - "description": "", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_clicks" } }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - } - }, - "404": { - "description": "\"\" : \"batch id not found\"", "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - }, - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "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" + } + ] + } + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "Update the status of a scheduled send." + ] } }, - "/user/settings/enforced_tls": { + "/subusers/stats/sums": { + "parameters": [], "get": { + "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": " Retrieve the totals for each email statistic metric for all subusers.", "consumes": [ "application/json" ], - "description": "", - "operationId": "Get the current Enforced TLS settings.", - "parameters": [], - "produces": [], - "responses": { - "default": { - "description": "", - "schema": {} - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "patch": { - "consumes": [ + "produces": [ "application/json" ], - "description": "", - "operationId": "Change the Enforced TLS settings", "parameters": [ { - "in": "body", - "name": "body", - "schema": { - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } - }, - "type": "object" - } + "name": "sort_by_direction", + "in": "query", + "description": "The direction you want to sort. ", + "required": false, + "type": "string", + "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" + }, + { + "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. 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" } ], - "produces": [], "responses": { - "default": { + "200": { "description": "", - "schema": {} + "schema": { + "$ref": "#/definitions/category_stats" + }, + "examples": { + "application/json": { + "date": "2015-10-11", + "stats": [] + } + } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/user/webhooks/parse/stats": { + "/subusers/stats": { + "parameters": [], "get": { + "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": "Retrieve email statistics for your subusers.", "consumes": [ "application/json" ], - "description": "", - "operationId": "Gets statistics for Parse Webhook usage.", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "query", "name": "limit", - "type": "string" + "in": "query", + "description": "Limits the number of results returned per page.", + "required": false, + "type": "integer" }, { - "in": "query", "name": "offset", - "type": "string" + "in": "query", + "description": "The point in the list to begin retrieving results from.", + "required": false, + "type": "integer" }, { - "in": "query", "name": "aggregated_by", - "type": "string" + "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", - "name": "start_date", + "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" } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "$ref": "#/definitions/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", + "date": "2015-10-01", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-22", + "date": "2015-10-02", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-23", + "date": "2015-10-03", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-24", + "date": "2015-10-04", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-25", + "date": "2015-10-05", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-26", + "date": "2015-10-06", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-27", + "date": "2015-10-07", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-28", + "date": "2015-10-08", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-29", + "date": "2015-10-09", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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-30", + "date": "2015-10-10", "stats": [ { + "type": "subuser", + "name": "Matt_subuser", "metrics": { - "received": 0 + "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 } } ] + } + ] + } + } + }, + "summary": "", + "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": { + "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": "Validate a Link Whitelabel", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The id of the link whitelabel." }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "received": 0 - } - } + "valid": { + "type": "boolean", + "description": "Indicates if the link whitelabel is valid.", + "enum": [ + true, + false ] }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "received": 0 + "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" + ] } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "received": 0 + } + } + }, + "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." + }, + "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" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/ips/pools/{pool_name}/ips/{ip}": { + "parameters": [ + { + "name": "pool_name", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "ip", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "description": "", + "operationId": "Remove an IP address from a pool.", + "consumes": [ + "application/json" + ], + "produces": [], + "parameters": [], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/ips/{ip_address}": { + "parameters": [ + { + "name": "ip_address", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "description": "", + "operationId": "See which pools an IP address belongs to.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "ip": { + "type": "string" }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "subusers": { + "type": "array", + "items": { + "type": "string" + } }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "rdns": { + "type": "string" }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "pools": { + "type": "array", + "items": { + "type": "string" + } }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "warmup": { + "type": "boolean" }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "received": 0 - } - } + "start_date": { + "type": [ + "integer", + "null" ] }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "whitelabeled": { + "type": "boolean" + } + } + }, + "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 + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/ips/pools/{pool_name}/ips": { + "parameters": [ + { + "name": "pool_name", + "in": "path", + "required": true, + "type": "string" + } + ], + "post": { + "description": "", + "operationId": "Add an IP to a pool", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "ip": { + "type": "string" + } + } + } + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "type": "object", + "properties": { + "ip": { + "type": "string" }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "pools": { + "type": "array", + "items": { + "type": "string" + } }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "start_date": { + "type": "integer" + }, + "warmup": { + "type": "boolean" } - ] + } }, + "examples": { + "application/json": { + "ip": "000.00.00.0", + "pools": [ + "test1" + ], + "start_date": 1409616000, + "warmup": true + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/api_key": { + "parameters": [], + "post": { + "description": "This will 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.\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", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "name": "body", + "in": "body", "schema": { - "items": { - "properties": { - "date": { + "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" - }, - "stats": { - "items": { - "properties": { - "metrics": { - "properties": { - "received": { - "type": "number" - } - }, - "type": "object" - } - } - }, - "type": "array" } - }, - "type": "object" + } }, - "type": "array" + "required": [ + "name" + ] + } + } + ], + "responses": { + "201": { + "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" + } + ] + } + } + }, + "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" + } + ] + } } } }, + "summary": "**Generate a new API Key for the authenticated user**\n\nThis will create a new random API Key for the user. A JSON reques", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [] + ] + } }, - "/whitelabel/domains": { + "/categories/stats": { + "parameters": [], "get": { + "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": "Retrieve Email Statistics for Categories", "consumes": [ "application/json" ], - "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": "List all domain whitelabels.", + "produces": [ + "application/json" + ], "parameters": [ { - "description": "Number of domains to return.", + "name": "start_date", "in": "query", - "name": "limit", - "type": "integer" + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD", + "required": true, + "type": "string" }, { - "description": "Paging offset.", + "name": "end_date", "in": "query", - "name": "offset", - "type": "integer" + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "required": false, + "type": "string" }, { - "description": "Exclude subuser domains from the result.", + "name": "categories", "in": "query", - "name": "exclude_subusers", - "type": "boolean" + "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", + "required": true, + "type": "string" }, { - "description": "The username associated with a whitelabel.", + "name": "limit", "in": "query", - "name": "username", - "type": "string" + "description": "The number of results to include.", + "required": false, + "type": "integer", + "maximum": 500 }, { - "description": "Search for domain whitelabels that match the given domain.", + "name": "offset", "in": "query", - "name": "domain", - "type": "string" + "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" + ] } ], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/category_stats" + } + }, "examples": { "application/json": [ { - "automatic_security": true, - "custom_spf": true, - "default": true, - "dns": { - "dkim1": { - "data": "s1._domainkey.u7.wl.sendgrid.net", - "host": "s1._domainkey.example.com", - "type": "cname", - "valid": true - }, - "dkim2": { - "data": "s2._domainkey.u7.wl.sendgrid.net", - "host": "s2._domainkey.example.com", - "type": "cname", - "valid": true - }, - "mail_cname": { - "data": "u7.wl.sendgrid.net", - "host": "mail.example.com", - "type": "cname", - "valid": true + "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 + } }, - "spf": { - "data": "v=spf1 include:u7.wl.sendgrid.net -all", - "host": "example.com", - "type": "txt", - "valid": true - } - }, - "domain": "example.com", - "id": 1, - "ips": [ - "192.168.1.1", - "192.168.1.2" - ], - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "john@example.com", - "valid": true + { + "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 + } + } + ] }, { - "automatic_security": true, - "custom_spf": false, - "default": true, - "dns": { - "dkim": { - "data": "k=rsa; t=s; p=publicKey", - "host": "example2.com", - "type": "txt", - "valid": false - }, - "domain_spf": { - "data": "v=spf1 include:news.example2.com -all", - "host": "example2.com", - "type": "txt", - "valid": false - }, - "mail_server": { - "data": "sendgrid.net", - "host": "news.example2.com", - "type": "mx", - "valid": false + "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 + } }, - "subdomain_spf": { - "data": "v=spf1 include:sendgrid.net ~all", - "host": "news.example2.com", - "type": "txt", - "valid": false + { + "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 + } } - }, - "domain": "example2.com", - "id": 2, - "ips": [], - "legacy": false, - "subdomain": "news", - "user_id": 8, - "username": "jane@example2.com", - "valid": false + ] } ] - }, - "schema": { - "items": { - "properties": { - "automatic_security": { - "description": "Indicates if this whitelabel uses automated security.", - "type": "boolean" - }, - "custom_spf": { - "description": "Indicates if this whitelabel has custom SPF.", - "type": "boolean" - }, - "default": { - "description": "Indicates if this whitelabel has been set as the default whitelabel.", - "type": "boolean" - }, - "dns": { - "description": "The DNS records for this whitelabel that are used for authenticating the sending domain.", - "properties": { - "dkim": { - "description": "The DNS record used when creating the DKIM signature.", - "properties": { - "data": { - "description": "The DNS record.", - "type": "string" - }, - "host": { - "description": "The domain that these DNS records will be applied to.", - "format": "hostname", - "type": "string" - }, - "type": { - "description": "The type of DNS record.", - "enum": [ - "cname", - "mx", - "txt" - ], - "type": "string" - }, - "valid": { - "description": "Indicates if this DNS record is valid.", - "type": "boolean" - } - }, - "type": "object" - }, - "mail_server": { - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "properties": { - "data": { - "description": "The mail server responsible for accepting messages.", - "type": "string" - }, - "host": { - "description": "The domain sending the messages.", - "type": "string" - }, - "type": { - "description": "The type of DNS record.", - "type": "string" - }, - "valid": { - "description": "Indicates if this is a valid DNS record with no conflicts.", - "type": "boolean" - } - }, - "type": "object" - }, - "subdomain_spf": { - "description": "The SPF record for the subdomain used to create this whitelabel.", - "properties": { - "data": { - "description": "The SPF record.", - "type": "string" - }, - "host": { - "description": "The domain that this SPF record will be used to authenticate.", - "type": "string" - }, - "type": { - "description": "The type of data in the SPF record.", - "type": "string" - }, - "valid": { - "description": "Indicates if the SPF record is valid.", - "type": "boolean" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "domain": { - "description": "The domain that this whitelabel was created for.", - "type": "string" - }, - "id": { - "description": "The ID of the domain whitelabel.", - "type": "number" - }, - "ips": { - "description": "The IPs that will be included in the custom SPF record.", - "items": { - "type": "string" - }, - "type": "array" - }, - "legacy": { - "description": "Indicates if this is whitelabel was created with the legacy whitelabel tool.", - "type": "boolean" - }, - "subdomain": { - "description": "The subdomain created for this domain whitelabel.", - "type": "string" - }, - "user_id": { - "description": "The ID of the user that this whitelabel will be associated with.", - "type": "number" - }, - "username": { - "description": "The username that this whitelabel is associated with.", - "type": "string" - }, - "valid": { - "description": "Indicates if this is a valid whitelabel or not.", - "type": "boolean" - } - }, - "required": [ - "id", - "user_id", - "subdomain", - "domain", - "username", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ], - "type": "object" - }, - "type": "array" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, + ] + } + }, + "/stats": { "parameters": [], - "post": { + "get": { + "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": "Retrieve global email statistics", "consumes": [ "application/json" ], - "description": "**This endpoint allows you to create a whitelabel for one of your domains.**\n\nIf you are creating a domain whitelabel that you would like a subuser to use, you have two options:\n1. 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.\n2. 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.\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": "Create a domain whitelabel.", + "produces": [ + "application/json" + ], "parameters": [ { - "in": "body", - "name": "body", - "schema": { - "properties": { - "automatic_security": { - "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.", - "type": "boolean" - }, - "custom_spf": { - "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.", - "type": "boolean" - }, - "default": { - "description": "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain.", - "type": "boolean" - }, - "domain": { - "description": "Domain being whitelabeled.", - "type": "string" - }, - "ips": { - "description": "The IP addresses that will be included in the custom SPF record for this whitelabel.", - "items": { - "type": "string" - }, - "type": "array" - }, - "subdomain": { - "description": "The subdomain to use for this domain whitelabel.", - "type": "string" - }, - "username": { - "description": "The username that this whitelabel will be associated with.", - "type": "string" - } - }, - "required": [ - "domain", - "subdomain" - ], - "type": "object" - } + "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" } ], - "produces": [ - "application/json" - ], "responses": { - "201": { + "200": { "description": "", - "examples": { - "application/json": { - "automatic_security": true, - "custom_spf": false, - "default": true, - "dns": { - "dkim1": { - "data": "s1.domainkey.u1446226.wl.sendgrid.net", - "host": "s1._domainkey.example.com", - "type": "cname", - "valid": false - }, - "dkim2": { - "data": "s2.domainkey.u1446226.wl.sendgrid.net", - "host": "s2._domainkey.example.com", - "type": "cname", - "valid": false + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date the stats were gathered." }, - "mail_cname": { - "data": "u1446226.wl.sendgrid.net", - "host": "example.example.com", - "type": "cname", - "valid": false + "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." + } + } + } + } + } } }, - "domain": "example.com", - "id": 302183, - "ips": [], - "legacy": false, - "subdomain": "example", - "user_id": 1446226, - "username": "mbernier", - "valid": false + "required": [ + "date", + "stats" + ] } }, - "schema": { - "$ref": "#/definitions/whitelabel::domain" + "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 + } + } + ] + } + ] } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "When creating a whitelabel for a subuser, there are two options available:\n Use the \"username\" parameter. This allows" + ] } }, - "/whitelabel/domains/default": { + "/categories/stats/sums": { + "parameters": [], "get": { + "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": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", "consumes": [ "application/json" ], - "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 the default domain whitelabel.", - "parameters": [], "produces": [ "application/json" ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" - } - } - }, - "security": [ + "parameters": [ { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [] - }, - "/whitelabel/domains/subuser": { - "delete": { - "consumes": [ - "application/json" - ], - "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": "Disassociate a domain whitelabel from a given user.", - "parameters": [], - "produces": [], - "responses": { - "204": { - "description": "" - } - }, - "security": [ + "name": "sort_by_metric", + "in": "query", + "description": "The metric that you want to sort by. Must be a single metric.", + "required": false, + "type": "string" + }, { - "Authorization": [] + "name": "sort_by_direction", + "in": "query", + "description": "The direction you want to sort.", + "required": false, + "type": "string", + "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" + }, + { + "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" + ] } ], - "summary": "Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows\nsubusers to send mail" - }, - "get": { - "consumes": [ - "application/json" - ], - "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": "List the domain whitelabel associated with the given user.", - "parameters": [], - "produces": [ - "application/json" - ], "responses": { "200": { "description": "", + "schema": { + "type": "object", + "properties": { + "": { + "$ref": "#/definitions/category_stats" + } + } + }, "examples": { "application/json": { - "automatic_security": false, - "custom_spf": true, - "default": false, - "dns": { - "dkim": { - "data": "k=rsa; t=s; p=publicKey", - "host": "s1._domainkey.example.com", - "type": "txt", - "valid": false + "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" }, - "domain_spf": { - "data": "v=spf1 include:mail.example.com -all", - "host": "example.com", - "type": "txt", - "valid": false + { + "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" }, - "mail_server": { - "data": "sendgrid.net", - "host": "mail.example.com", - "type": "mx", - "valid": false + { + "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" }, - "subdomain_spf": { - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "host": "mail.example.com", - "type": "txt", - "valid": false + { + "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" } - }, - "domain": "example.com", - "id": 1, - "ips": [], - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "mail@example.com", - "valid": false + ] } - }, - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [] + ] + } }, - "/whitelabel/domains/{domain_id}": { - "delete": { - "consumes": [ - "application/json" - ], - "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 a domain whitelabel.", - "parameters": [], - "produces": [], - "responses": { - "204": { - "description": "" - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "get": { + "/user/webhooks/event/settings": { + "parameters": [], + "patch": { + "description": "", + "operationId": "Update Event Notification Settings", "consumes": [ "application/json" ], - "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": "Retrieve a domain whitelabel.", - "parameters": [], "produces": [ "application/json" ], - "responses": { - "200": { - "description": "", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { - "$ref": "#/definitions/whitelabel::domain" + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "url": { + "type": "string" + }, + "group_resubscribe": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "spamreport": { + "type": "boolean" + }, + "bounce": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "unsubscribe": { + "type": "boolean" + }, + "processed": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + } + } } } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [ - { - "description": "The id of the domain whitelabel.", - "in": "path", - "name": "id", - "required": true, - "type": "string" - } - ], - "patch": { - "consumes": [ - "application/json" ], - "description": "**This endpoint allows you to update the settings for 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": "Update a domain whitelabel.", - "parameters": [ - { - "in": "body", - "name": "body", + "responses": { + "200": { + "description": "", "schema": { + "type": "object", "properties": { - "custom_spf": { - "default": "false", - "description": "Indicates whether to generate a custom SPF record for manual security.", + "enabled": { + "type": "boolean" + }, + "url": { + "type": "string" + }, + "group_resubscribe": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "spamreport": { + "type": "boolean" + }, + "bounce": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "unsubscribe": { "type": "boolean" }, - "default": { - "default": "false", - "description": "Indicates whether this domain whitelabel should be considered the default.", + "processed": { "type": "boolean" - } - }, - "type": "object" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "properties": { - "custom_spf false": { - "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", + }, + "open": { "type": "boolean" }, - "default false": { - "description": "Inidcates whether this domain whitelabel should be considered the default. Defaults to false.", + "click": { + "type": "boolean" + }, + "dropped": { "type": "boolean" } - }, - "title": "Update a Domain response", - "type": "object" + } + }, + "examples": { + "application/json": { + "enabled": true, + "url": "url", + "group_resubscribe": true, + "delivered": true, + "group_unsubscribe": true, + "spamreport": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": true, + "dropped": true + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - } - }, - "/whitelabel/domains/{domain_id}/subuser": { - "parameters": [ - { - "in": "path", - "name": "domain_id", - "required": true, - "type": "string" - } - ], - "post": { + ] + }, + "get": { + "description": "", + "operationId": "Retrieve Event Webhook Settings", "consumes": [ "application/json" ], - "description": "**This endpoint allows you to associate a specific domain whitelabel with 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 | Description |\n|---|---|---|\n| domain_id | integer | ID of the domain whitelabel to associate with the subuser. |", - "operationId": "Associate a domain whitelabel with a given user.", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "properties": { - "username": { - "description": "Username to associate with the domain whitelabel.", - "type": "string" - } - }, - "required": [ - "username" - ], - "type": "object" - } - } - ], "produces": [ "application/json" ], + "parameters": [], "responses": { - "201": { + "200": { "description": "", - "examples": { - "application/json": { - "automatic_security": false, - "custom_spf": true, - "default": false, - "dns": { - "dkim": { - "data": "k=rsa; t=s; p=publicKey", - "host": "s1._domainkey.example.com", - "type": "txt", - "valid": false - }, - "domain_spf": { - "data": "v=spf1 include:mail.example.com -all", - "host": "example.com", - "type": "txt", - "valid": false - }, - "mail_server": { - "data": "sendgrid.net", - "host": "mail.example.com", - "type": "mx", - "valid": false - }, - "subdomain_spf": { - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "host": "mail.example.com", - "type": "txt", - "valid": false - } + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - "domain": "example.com", - "id": 1, - "ips": [], - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "mail@example.com", - "valid": false + "url": { + "type": "string" + }, + "group_resubscribe": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "spam_report": { + "type": "boolean" + }, + "bounce": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "unsubscribe": { + "type": "boolean" + }, + "processed": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + } } }, - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" + "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 + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/whitelabel/domains/{id}/ips": { - "parameters": [ - { - "in": "path", - "name": "id", - "required": true, - "type": "string" - } - ], + "/user/webhooks/event/test": { + "parameters": [], "post": { + "description": "", + "operationId": "Test Event Notification Settings ", "consumes": [ "application/json" ], - "description": "**This endpoint allows you to add an IP address to 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)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain to which you are adding an IP |", - "operationId": "Add an IP to a domain whitelabel.", + "produces": [], "parameters": [ { - "in": "body", "name": "body", + "in": "body", "schema": { + "type": "object", "properties": { - "ip": { - "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF.", + "url": { "type": "string" } - }, - "required": [ - "ip" - ], - "type": "object" + } } } ], - "produces": [ - "application/json" - ], "responses": { - "200": { + "204": { "description": "", - "examples": { - "application/json": { - "automatic_security": false, - "custom_spf": true, - "default": false, - "dns": { - "dkim": { - "data": "k=rsa; t=s; p=publicKey", - "host": "s1._domainkey.example.com", - "type": "txt", - "valid": false - }, - "domain_spf": { - "data": "v=spf1 include:mail.example.com -all", - "host": "example.com", - "type": "txt", - "valid": false - }, - "mail_server": { - "data": "sendgrid.net", - "host": "mail.example.com", - "type": "mx", - "valid": false - }, - "subdomain_spf": { - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "host": "mail.example.com", - "type": "txt", - "valid": false - } - }, - "domain": "example.com", - "id": 1, - "ips": [], - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "john@example.com", - "valid": false - } - }, "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" + "type": "object", + "properties": {} } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" + ] } }, - "/whitelabel/domains/{id}/ips/{ip}": { - "delete": { + "/user/webhooks/parse/settings": { + "parameters": [], + "get": { + "description": "", + "operationId": "Retrieve Parse API settings", "consumes": [ "application/json" ], - "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": "Remove an IP from a domain whitelabel.", - "parameters": [], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "automatic_security": false, - "custom_spf": true, - "default": false, - "dns": { - "dkim": { - "data": "k=rsa; t=s; p=publicKey", - "host": "s1._domainkey.example.com", - "type": "txt", - "valid": false - }, - "domain_spf": { - "data": "v=spf1 include:mail.example.com -all", - "host": "example.com", - "type": "txt", - "valid": false - }, - "mail_server": { - "data": "sendgrid.net", - "host": "mail.example.com", - "type": "mx", - "valid": false - }, - "subdomain_spf": { - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "host": "mail.example.com", - "type": "txt", - "valid": false + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "type": "object", + "properties": { + "hostname": { + "type": "string" + }, + "url": { + "type": "string" + }, + "spam_check": { + "type": "boolean" + }, + "send_raw": { + "type": "boolean" + } + } } - }, - "domain": "example.com", - "id": 1, - "ips": [], - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "mail@example.com", - "valid": false + } } }, - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" + "examples": { + "application/json": { + "result": [ + { + "hostname": "example.com", + "url": "http://example.com/example", + "spam_check": false, + "send_raw": false + } + ] + } } } }, + "summary": "", "security": [ { "Authorization": [] } - ], - "summary": "" - }, - "parameters": [ - { - "in": "path", - "name": "id", - "required": true, - "type": "string" - }, - { - "in": "path", - "name": "ip", - "required": true, - "type": "string" - } - ] + ] + } }, - "/whitelabel/domains/{id}/validate": { + "/whitelabel/ips/{id}/validate": { "parameters": [ { - "in": "path", "name": "id", + "in": "path", "required": true, - "type": "string" + "type": "integer" } ], "post": { + "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": "Validate an IP whitelabel", "consumes": [ "application/json" ], - "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": "Validate a domain whitelabel.", - "parameters": [], "produces": [ "application/json" ], + "parameters": [], "responses": { "200": { "description": "", - "examples": { - "application/json": { - "id": 1, - "valid": true, - "validation_resuts": { - "dkim1": { - "reason": null, - "valid": true - }, - "dkim2": { - "reason": null, - "valid": true - }, - "mail_cname": { - "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\".", - "valid": false - }, - "spf": { - "reason": null, - "valid": true - } - } - } - }, "schema": { + "type": "object", "properties": { "id": { - "description": "The ID of the domain whitelabel.", - "type": "integer" + "type": "integer", + "description": "The id of the IP whitelabel." }, "valid": { - "description": "Indicates if this is a valid whitelabel.", - "type": "boolean" + "type": "boolean", + "description": "Indicates if the IP whitelabel is valid.", + "enum": [ + true, + false + ] }, - "validation_resuts": { - "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", + "validation_results": { + "type": "object", + "description": "The specific results of the validation.", "properties": { - "dkim1": { - "description": "A DNS record for this domain whitelabel.", - "properties": { - "reason": { - "type": "null" - }, - "valid": { - "description": "Indicates if the DNS record is valid.", - "type": "boolean" - } - }, - "type": "object" - }, - "dkim2": { - "description": "A DNS record for this whitelabel.", + "a_record": { + "type": "object", "properties": { - "reason": { - "type": "null" - }, "valid": { - "description": "Indicates if the DNS record is valid.", - "type": "boolean" - } - }, - "type": "object" - }, - "mail_cname": { - "description": "The CNAME record for the domain whitelabel.", - "properties": { - "reason": { - "description": "The reason this record is invalid.", - "type": "string" + "type": "boolean", + "description": "Indicates if the IP whitelabel could be validated.", + "enum": [ + true, + false + ] }, - "valid": { - "description": "Indicates if this DNS record is valid.", - "type": "boolean" - } - }, - "type": "object" - }, - "spf": { - "description": "The SPF record for the whitelabel.", - "properties": { "reason": { - "type": "null" - }, - "valid": { - "description": "Indicates if the SPF record is valid.", - "type": "boolean" + "type": [ + "null", + "string" + ], + "description": "The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated." } }, - "type": "object" + "required": [ + "valid", + "reason" + ] } - }, - "type": "object" + } } }, - "type": "object" + "required": [ + "id", + "valid", + "validation_results" + ] + }, + "examples": { + "application/json": { + "id": 1, + "valid": true, + "validation_results": { + "a_record": { + "valid": true, + "reason": null + } + } + } } }, - "400": { + "404": { "description": "Unexpected error in API call. See HTTP response body for details.", "schema": { - "properties": {}, - "type": "object" - } - }, - "500": { - "description": "", + "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": "internal error getting TXT" + "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": { - "description": "A message explaining the reason for the error.", - "type": "string" + "type": "string", + "description": "A message describing why the IP whitelabel could not be validated." } }, "required": [ "message" - ], - "type": "object" - }, - "type": "array" + ] + } } }, - "type": "object" + "required": [ + "errors" + ] + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "internal error getting rDNS" + } + ] + } + } + } + }, + "summary": "", + "security": [ + { + "Authorization": [] + } + ] + } + } + }, + "definitions": { + "contacts": { + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "address2": {}, + "city": { + "type": "string" + }, + "company": { + "type": "string" + }, + "country": { + "type": "string" + }, + "email": { + "type": "string" + }, + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "phone": { + "type": "string" + }, + "state": { + "type": "string" + }, + "zip": { + "type": "string" + } + } + }, + "subuser": { + "title": "List all Subusers for a parent response", + "type": "object", + "properties": { + "disabled": { + "type": "boolean", + "description": "Whether or not the user is enabled or disabled." + }, + "id": { + "type": "number", + "description": "The ID of this subuser." + }, + "username": { + "type": "string", + "description": "The name by which this subuser will be referred." + }, + "email": { + "type": "string", + "description": "The email address to contact this subuser.", + "format": "email" + } + }, + "required": [ + "disabled", + "id", + "username", + "email" + ] + }, + "contactdb_segments_conditions": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "value": { + "type": "string" + }, + "operator": { + "type": "string", + "enum": [ + "eq", + "ne", + "lt", + "gt", + "contains" + ] + }, + "and_or": { + "type": "string", + "enum": [ + "and", + "or", + "" + ] + } + }, + "required": [ + "field", + "value", + "operator" + ] + }, + "subuser_post": { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The username of the subuser." + }, + "user_id": { + "type": "number", + "description": "The user ID for this subuser." + }, + "email": { + "type": "string", + "description": "The email address for this subuser.", + "format": "email" + }, + "signup_session_token": { + "type": "string" + }, + "authorization_token": { + "type": "string" + }, + "credit_allocation": { + "type": "object", + "properties": { + "type": { + "type": "string" } } + } + }, + "required": [ + "username", + "user_id", + "email" + ] + }, + "contactdb_segments": { + "title": "Create a Segment request", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of this segment." }, - "security": [ - { - "Authorization": [] + "list_id": { + "type": "integer", + "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." + }, + "conditions": { + "type": "array", + "description": "The conditions for a recipient to be included in this segment.", + "items": { + "$ref": "#/definitions/contactdb_segments_conditions" } - ], - "summary": "" - } + }, + "recipient_count": { + "type": "number", + "description": "The count of recipients in this list. This is not included on creation of segments." + } + }, + "required": [ + "name", + "conditions" + ] }, - "/whitelabel/ips": { - "get": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "List all IPs", - "parameters": [ - { - "in": "query", - "name": "limit", + "campaign_request": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." + }, + "subject": { + "type": [ + "string", + "null" + ], + "description": "The subject of your campaign that your recipients will see." + }, + "sender_id": { + "type": [ + "null", + "integer" + ], + "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails." + }, + "list_ids": { + "type": [ + "array", + "null" + ], + "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", + "items": { + "type": "integer" + } + }, + "segment_ids": { + "type": [ + "array", + "null" + ], + "description": "The segment IDs that you are sending this list to. You can have both segment IDs and list IDs.", + "items": { + "type": "integer" + } + }, + "categories": { + "type": [ + "array", + "null" + ], + "description": "The categories you would like associated to this campaign.", + "items": { "type": "string" } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": [ - { - "a_record": { - "data": "192.168.1.1", - "host": "o1.email.example.com", - "type": "a", - "valid": true - }, - "domain": "example.com", - "id": 1, - "ip": "192.168.1.1", - "legacy": false, - "rdns": "o1.email.example.com", - "subdomain": "email", - "users": [ - { - "user_id": 7, - "username": "john@example.com" - }, - { - "user_id": 8, - "username": "jane@example.com" - } - ], - "valid": true - }, - { - "a_record": { - "data": "192.168.1.2", - "host": "o2.email.example.com", - "type": "a", - "valid": true - }, - "domain": "example.com", - "id": 2, - "ip": "192.168.1.2", - "legacy": false, - "rnds": "o2.email.example.com", - "subdomain": "email", - "users": [ - { - "user_id": 7, - "username": "john@example.com" - }, - { - "user_id": 9, - "username": "jane@example2.com" - } - ], - "valid": true - } - ] - }, - "schema": { - "items": { - "properties": { - "a_record": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - }, - "domain": { - "type": "string" - }, - "id": { - "type": "number" - }, - "ip": { - "type": "string" - }, - "legacy": { - "type": "boolean" - }, - "rdns": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "users": { - "items": { - "properties": { - "user_id": { - "type": "number" - }, - "username": { - "type": "string" - } - } - }, - "type": "array" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - }, - "type": "array" - } + }, + "suppression_group_id": { + "type": [ + "null", + "integer" + ], + "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type." + }, + "custom_unsubscribe_url": { + "type": [ + "string", + "null" + ], + "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups." + }, + "ip_pool": { + "type": [ + "string", + "null" + ], + "description": "The pool of IPs that you would like to send this email from." + }, + "html_content": { + "type": [ + "string", + "null" + ], + "description": "The HTML of your marketing email." + }, + "plain_content": { + "type": [ + "string", + "null" + ], + "description": "The plain text content of your emails." + } + }, + "required": [ + "title" + ] + }, + "contactdb_recipient_response": { + "type": "object", + "properties": { + "error_count": { + "type": "number", + "default": "0", + "description": "The number of errors found while adding recipients." + }, + "error_indices": { + "type": "array", + "default": "[]", + "description": "The indices of the recipient(s) sent that caused the error. ", + "items": { + "type": "number" } }, - "security": [ - { - "Authorization": [] + "new_count": { + "type": "number", + "default": "0", + "description": "The count of new recipients added to the contactdb." + }, + "persisted_recipients": { + "type": "array", + "default": "[]", + "description": "The recipient IDs of the recipients that already existed from this request.", + "items": { + "type": "string" } - ], - "summary": "" - }, - "parameters": [], - "post": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Create an IP", - "parameters": [ - { - "in": "body", - "name": "body", - "schema": { - "properties": { - "domain": { - "type": "string" - }, - "ip": { - "type": "string" - }, - "subdomain": { - "type": "string" - } + }, + "updated_count": { + "type": "number", + "default": "0", + "description": "The recipients who were updated from this request." + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" }, - "type": "object" + "error_indices": { + "type": "array", + "items": { + "type": "number" + } + } } } - ], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "examples": { - "application/json": { - "a_record": { - "data": "192.168.1.2", - "host": "o1.email.example.com", - "type": "a", - "valid": true - }, - "domain": "example.com", - "id": 123, - "ip": "192.168.1.2", - "legacy": false, - "rnds": "o1.email.example.com", - "subdomain": "email", - "users": [], - "valid": true + } + }, + "required": [ + "error_count", + "new_count", + "persisted_recipients", + "updated_count" + ] + }, + "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" + ] + }, + "api_key_name_id_scopes": { + "allOf": [ + { + "type": "object", + "properties": { + "scopes": { + "type": "array", + "description": "The permissions this API Key has access to.", + "items": { + "type": "string" } + } + } + }, + { + "$ref": "#/definitions/api_key_name_id" + } + ] + }, + "credentials": { + "type": "object", + "properties": { + "permissions": { + "type": "object", + "properties": { + "api": { + "type": "string" }, - "schema": { - "properties": { - "a_record": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - }, - "domain": { - "type": "string" - }, - "id": { - "type": "integer" - }, - "ip": { - "type": "string" - }, - "legacy": { - "type": "boolean" - }, - "rnds": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "users": { - "items": {}, - "type": "array" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" + "mail": { + "type": "string" + }, + "web": { + "type": "string" + } + } + }, + "username": { + "type": "string" + } + } + }, + "partner_settings_new_relic": { + "type": "object", + "properties": { + "enable_subuser_statistics": { + "type": "boolean", + "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this setting is enabled. " + }, + "license_key": { + "type": "string", + "description": "The license key provided with your New Relic account." + } + }, + "required": [ + "enabled", + "license_key" + ] + }, + "suppression_group_unsubscribes": { + "type": "object", + "allOf": [ + { + "$ref": "#/definitions/suppression_group" + }, + { + "type": "object", + "required": [ + "unsubscribes" + ], + "properties": { + "unsubscribes": { + "type": "integer", + "description": "The unsubscribes associated with this group." } } + } + ] + }, + "mail_settings_forward_bounce": { + "type": "object", + "properties": { + "email": { + "type": [ + "string", + "null" + ] + }, + "enabled": { + "type": "boolean" + } + } + }, + "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." + } + } + }, + "monitor": { + "title": "Create monitor settings request", + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address to send emails at the frequency specified for monitoring.", + "format": "email" + }, + "frequency": { + "type": "number", + "description": "The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. " + } + }, + "required": [ + "email", + "frequency" + ] + }, + "global:id": { + "type": "integer" + }, + "mail_settings_template": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "html_content": { + "type": "string" + } + } + }, + "mail_settings_spam_check": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" + "max_score": { + "type": "integer" + }, + "url": { + "type": "string" + } } }, - "/whitelabel/ips/{id}": { - "delete": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Delete an IP", - "parameters": [], - "produces": [], - "responses": { - "204": { - "description": "", - "schema": { - "properties": {}, - "type": "object" - } - } + "mail_settings_forward_spam": { + "type": "object", + "properties": { + "email": { + "type": [ + "string", + "null" + ] }, - "security": [ - { - "Authorization": [] + "enabled": { + "type": "boolean" + } + } + }, + "mail_settings::patch": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "email": { + "type": "string" + } + } + }, + "mail_settings_bounce_purge": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "soft_bounces": { + "type": [ + "integer", + "null" + ] + }, + "hard_bounces": { + "type": [ + "integer", + "null" + ] + } + } + }, + "mail_settings_bcc": { + "type": "object", + "properties": { + "email": { + "type": "string" + }, + "enabled": { + "type": "boolean" + } + } + }, + "mail_settings_address_whitelabel": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "list": { + "type": "array", + "items": { + "type": "string" } - ], - "summary": "" + } + } + }, + "global:empty_request": { + "type": "null" + }, + "mail_batch_id": { + "type": "object", + "properties": { + "batch_id": { + "type": "string", + "pattern": "^[a-zA-Z0-9\\-\\_]" + } }, - "get": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Retrieve an IP", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "a_record": { - "data": "192.168.1.1", - "host": "o1.email.example.com", - "type": "a", - "valid": true - }, - "domain": "example.com", - "ip": "192.168.1.1", - "legacy": false, - "rdns": "o1.email.example.com", - "subdomain": "email", - "users": [ - { - "user_id": 7, - "username": "john@example.com" - } - ], - "valid": true - } + "required": [ + "batch_id" + ] + }, + "campaign_response": { + "allOf": [ + { + "$ref": "#/definitions/campaign_request" + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "The status of your campaign." }, - "schema": { - "properties": { - "a_record": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - }, - "domain": { - "type": "string" - }, - "ip": { - "type": "string" - }, - "legacy": { - "type": "boolean" - }, - "rdns": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "users": { - "items": { - "properties": { - "user_id": { - "type": "integer" - }, - "username": { - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" + "id": { + "type": "integer" } - } + }, + "required": [ + "status" + ] + } + ] + }, + "contactdb_segments_with_id": { + "allOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The ID of the segment." + } + }, + "required": [ + "id" + ] }, - "security": [ - { - "Authorization": [] + { + "$ref": "#/definitions/contactdb_segments" + } + ] + }, + "contactdb_custom_field_with_id_value": { + "allOf": [ + { + "$ref": "#/definitions/contactdb_custom_field_with_id" + }, + { + "type": "object", + "properties": { + "value": { + "type": [ + "string", + "null" + ], + "description": "The value of this recipient's custom field" + } } - ], - "summary": "" - }, - "parameters": [ + } + ], + "title": "ContactDB Custom field schema." + }, + "contactdb_custom_field_with_id": { + "allOf": [ { - "in": "path", - "name": "id", - "required": true, - "type": "string" + "$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", + "properties": { + "name": { + "type": "string", + "description": "The name of the field" + }, + "type": { + "type": "string", + "description": "The type of the field.", + "enum": [ + "date", + "text", + "number" + ] } + } + }, + "contactdb_recipient_count": { + "type": "object", + "properties": { + "recipient_count": { + "type": "number", + "description": "The count of recipients." + } + }, + "required": [ + "recipient_count" ] }, - "/whitelabel/ips/{id}/validate": { - "parameters": [ - { - "in": "path", - "name": "id", - "required": true, + "mail_settings_footer": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "html_content": { + "type": "string" + }, + "plain_content": { "type": "string" } - ], - "post": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "Validate an IP", - "parameters": [], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": { - "id": 1, - "valid": true, - "validation_results": { - "a_record": { - "reason": null, - "valid": true - } - } - } - }, - "schema": { - "properties": { - "id": { - "type": "integer" - }, - "valid": { - "type": "boolean" - }, - "validation_results": { - "properties": { - "a_record": { - "properties": { - "reason": { - "type": "null" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - } - }, - "type": "object" - } - }, - "type": "object" + } + }, + "user_scheduled_send_status": { + "allOf": [ + { + "$ref": "#/definitions/mail_batch_id" + }, + { + "type": "object", + "description": "The status of the scheduled send.", + "properties": { + "status": { + "type": "string", + "description": "The status of the scheduled send.", + "enum": [ + "cancel", + "pause" + ] } }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details." - } + "required": [ + "status" + ] + } + ] + }, + "contactdb_list": { + "title": "ContactDB lists", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The reference ID of your list." }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } + "name": { + "type": "string", + "description": "The name of your list." + }, + "recipient_count": { + "type": "integer", + "description": "The count of recipients currently in the list." + } + }, + "required": [ + "id", + "name", + "recipient_count" + ] }, - "/whitelabel/links": { - "get": { - "consumes": [ - "application/json" - ], - "description": "", - "operationId": "List all Links", - "parameters": [ - { - "in": "query", - "name": "limit", - "type": "string" - } - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "examples": { - "application/json": [ - { - "default": true, - "dns": { - "domain_cname": { - "data": "sendgrid.net", - "host": "mail.example.com", - "type": "cname", - "valid": true - }, - "owner_cname": { - "data": "sendgrid.net", - "host": "7.example.com", - "type": "cname", - "valid": true - } - }, - "domain": "example.com", - "id": 1, - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "john@example.com", - "valid": true - }, - { - "default": false, - "dns": { - "domain_cname": { - "data": "sendgrid.net", - "host": "news.example2.com", - "type": "cname", - "valid": true - }, - "owner_cname": { - "data": "sendgrid.net", - "host": "8.example2.com", - "type": "cname", - "valid": false - } - }, - "domain": "example2.com", - "id": 2, - "legacy": false, - "subdomain": "news", - "user_id": 8, - "username": "john@example.com", - "valid": false - } - ] - }, - "schema": { - "items": { - "properties": { - "default": { - "type": "boolean" - }, - "dns": { - "properties": { - "domain_cname": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - }, - "owner_cname": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "domain": { - "type": "string" - }, - "id": { - "type": "integer" - }, - "legacy": { - "type": "boolean" - }, - "subdomain": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "username": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" + "user_profile": { + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "address2": { + "type": "string" + }, + "city": { + "type": "string" + }, + "company": { + "type": "string" + }, + "country": { + "type": "string" + }, + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "phone": { + "type": "string" + }, + "state": { + "type": "string" + }, + "website": { + "type": "string" + }, + "zip": { + "type": "string" + } + } + }, + "global:ErrorResponse": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." }, - "type": "array" - } + "message": { + "type": "string", + "description": "The error message." + } + }, + "required": [ + "message" + ] } + } + } + }, + "suppression_bounce": { + "type": "object", + "properties": { + "created": { + "type": "number", + "description": "The unix timestamp for when the bounce record was created at SendGrid." }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - }, - "parameters": [], - "post": { - "consumes": [ - "application/json" - ], - "description": "This is a place for notes and extra information about this endpoint. It is written\nin Markdown - more info in the [documentation](/docs/designer#markdown).\n\nThere are several special markdown helpers that automatically build tables\nand html off of your endpoint definition. You can find some examples in this content.\n\nClick the \"Open Editor\" button above to start editing this content.", - "operationId": "Create a Link", - "parameters": [ - { - "description": "Number of domains to return. Defaults to 50.", - "in": "query", - "name": "limit", - "type": "number" - }, - { - "description": "Paging offset. Defaults to 0.", - "in": "query", - "name": "offset", - "type": "number" - }, - { - "in": "body", - "name": "body", - "schema": { - "properties": { - "default": { - "type": "boolean" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" + "email": { + "type": "string" + }, + "reason": { + "type": "string", + "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." + }, + "status": { + "type": "string", + "description": "Enhanced SMTP bounce response" + } + } + }, + "contactdb_recipient": { + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of this recipient." + }, + "created_at": { + "type": "number", + "description": "The time this record was created in your contactdb, in unixtime." + }, + "custom_fields": { + "type": "array", + "description": "The custom fields assigned to this recipient and their values.", + "items": { + "$ref": "#/definitions/contactdb_custom_field_with_id_value" } }, - "type": "object" - } - } - ], - "produces": [ - "application/json" - ], - "responses": { - "201": { - "description": "", - "examples": { - "application/json": { - "default": false, - "dns": { - "domain_cname": { - "data": "sendgrid.net", - "host": "mail.example.com", - "type": "cname", - "valid": true - }, - "owner_cname": { - "data": "sendgrid.net", - "host": "7.example.com", - "type": "cname", - "valid": true - } - }, - "domain": "example.com", - "id": 1, - "legacy": false, - "subdomain": "mail", - "user_id": 7, - "username": "john@example.com", - "valid": true + "email": { + "type": "string", + "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", + "format": "email" + }, + "first_name": { + "type": [ + "string", + "null" + ], + "description": "The first name of this recipient. This is a default custom field that SendGrid provides." + }, + "last_name": { + "type": [ + "string", + "null" + ], + "description": "The last name of the recipient." + }, + "last_clicked": { + "type": [ + "number", + "null" + ], + "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." + }, + "last_emailed": { + "type": [ + "number", + "null" + ], + "description": "The last time this user was emailed by one of your campaigns, in unixtime." + }, + "last_opened": { + "type": [ + "number", + "null" + ], + "description": "The last time this recipient opened an email from you, in unixtime." + }, + "updated_at": { + "type": "number", + "description": "The last update date for this recipient's record." } }, - "schema": { - "properties": { - "default": { - "type": "boolean" - }, - "dns": { - "properties": { - "domain_cname": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - }, - "owner_cname": { - "properties": { - "data": { - "type": "string" - }, - "host": { - "type": "string" - }, - "type": { - "type": "string" - }, - "valid": { - "type": "boolean" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "domain": { - "type": "string" - }, - "id": { - "type": "integer" - }, - "legacy": { - "type": "boolean" - }, - "subdomain": { - "type": "string" + "required": [ + "email" + ] + } + } + } + }, + "whitelabel::domain": { + "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 to use for this domain whitelabel." + }, + "domain": { + "type": "string", + "description": "The domain that this whitelabel is being created for." + }, + "username": { + "type": "string", + "description": "The username that this whitelabel will be associated with." + }, + "ips": { + "type": "array", + "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", + "items": { + "type": "object", + "properties": {} + } + }, + "custom_spf": { + "type": "boolean", + "description": "Indicates whether this domain whitelabel will use custom SPF." + }, + "default": { + "type": "boolean", + "description": "Indicates if this domain whitelabel is the default whitelabel." + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." + }, + "automatic_security": { + "type": "boolean", + "description": "Indicates if this domain whitelabel uses automated security." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid whitelabel." + }, + "dns": { + "type": "object", + "description": "The DNS records for this whitelabel that are used to authenticate the sending domain.", + "required": [ + "mail_cname", + "dkim1", + "dkim2" + ], + "properties": { + "mail_cname": { + "type": "object", + "description": "The CNAME for your sending domain that points to sendgrid.net.", + "required": [ + "valid", + "type", + "host", + "data" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid CNAME." }, - "user_id": { - "type": "integer" + "type": { + "type": "string", + "description": "The type of DNS record." }, - "username": { - "type": "string" + "host": { + "type": "string", + "description": "The domain that this CNAME is created for.", + "format": "hostname" }, - "valid": { - "type": "boolean" + "data": { + "type": "string", + "description": "The CNAME record." } - }, - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ], - "summary": "" - } - }, - "/whitelabel/links/default": { - "get": { - "consumes": [ - "application/json" - ], - "description": "Default link 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