openapi-directory
Version:
Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS
1 lines • 513 kB
JSON
{"openapi":"3.0.0","info":{"description":"# The SendGrid Web API V3 Documentation\n\nThis is the entirety of the documented v3 endpoints. We have updated all the descriptions, parameters, requests, and responses.\n\n## Authentication \n\nEvery endpoint requires Authentication in the form of an Authorization Header:\n\nAuthorization: Bearer API_KEY","title":"SendGrid v3","version":"3.0","x-apisguru-categories":["email","marketing"],"x-logo":{"url":"https://user-images.githubusercontent.com/21603/27865240-b4c0da22-6189-11e7-9f2c-f35f4c6fa57c.png"},"x-origin":[{"format":"swagger","url":"https://raw.githubusercontent.com/sendgrid/sendgrid-oai/master/oai.json","version":"2.0"}],"x-providerName":"sendgrid.com"},"externalDocs":{"url":"https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html"},"paths":{"/access_settings/activity":{"get":{"description":"**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).","operationId":"GET_access_settings-activity","parameters":[{"description":"Limits the number of IPs to return.","in":"query","name":"limit","schema":{"type":"integer","default":20}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"result":{"items":{"properties":{"allowed":{"type":"boolean"},"auth_method":{"type":"string"},"first_at":{"type":"integer"},"ip":{"type":"string"},"last_at":{"type":"integer"},"location":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"examples":{"response":{"value":{"result":[{"allowed":false,"auth_method":"basic","first_at":1444087966,"ip":"1.1.1.1","last_at":1444406672,"location":"Australia"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve all recent access attempts","tags":["IP Access Management"]}},"/access_settings/whitelist":{"delete":{"description":"**This endpoint allows you to remove one or more IPs from your IP whitelist.**\n\nYou can remove one IP at a time, or you can remove multiple IP addresses.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).","operationId":"DELETE_access_settings-whitelist","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"ids":[1,2,3]},"properties":{"ids":{"description":"An array of the IDs of the IP address that you want to remove from your whitelist.","items":{"type":"integer"},"type":"array"}},"type":"object"}}}},"responses":{"204":{"description":"","content":{"application/json":{"schema":{"properties":{},"type":"object"}}}}},"security":[{"Authorization":[]}],"summary":"Remove one or more IPs from the whitelist","tags":["IP Access Management"]},"get":{"description":"**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).","operationId":"GET_access_settings-whitelist","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"result":{"description":"An array listing all of your whitelisted IPs.","items":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the IP was whitelisted.","type":"integer"},"id":{"description":"The ID of the whitelisted IP.","type":"integer"},"ip":{"description":"The whitelisted IP.","type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the IPs whitelisting status was most recently updated.","type":"integer"}},"required":["id","ip","created_at","updated_at"],"type":"object"},"type":"array"}},"required":["result"],"type":"object"},"examples":{"response":{"value":{"result":[{"created_at":1441824715,"id":1,"ip":"192.168.1.1/32","updated_at":1441824715},{"created_at":1441824715,"id":2,"ip":"192.168.1.2/32","updated_at":1441824715},{"created_at":1441824715,"id":3,"ip":"192.168.1.3/32","updated_at":1441824715}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve a list of currently whitelisted IPs","tags":["IP Access Management"]},"post":{"description":"**This endpoint allows you to add one or more IP addresses to your IP whitelist.**\n\nWhen adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).","operationId":"POST_access_settings-whitelist","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"ips":[{"ip":"192.168.1.1"},{"ip":"192.*.*.*"},{"ip":"192.168.1.3/32"}]},"properties":{"ips":{"description":"An array containing the IP(s) you want to whitelist.","items":{"properties":{"ip":{"description":"An IP address that you want to whitelist.","type":"string"}},"required":["ip"],"type":"object"},"type":"array"}},"required":["ips"],"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"result":{"description":"An array listing all of your whitelisted IPs.","items":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the IP was whitelisted.","type":"integer"},"id":{"description":"The ID of the whitelisted IP.","type":"integer"},"ip":{"description":"The whitelisted IP.","type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the IPs whitelisting status was most recently updated.","type":"integer"}},"required":["id","ip","created_at","updated_at"],"type":"object"},"type":"array"}},"required":["result"],"type":"object"},"examples":{"response":{"value":{"result":[{"created_at":1441824715,"id":1,"ip":"192.168.1.1/32","updated_at":1441824715},{"created_at":1441824715,"id":2,"ip":"192.0.0.0/8","updated_at":1441824715},{"created_at":1441824715,"id":3,"ip":"192.168.1.3/32","updated_at":1441824715}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Add one or more IPs to the whitelist","tags":["IP Access Management"]}},"/access_settings/whitelist/{rule_id}":{"delete":{"description":"**This endpoint allows you to remove a specific IP address from your IP whitelist.**\n\nWhen removing a specific IP address from your whitelist, you must include the ID in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).","operationId":"DELETE_access_settings-whitelist-rule_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/DELETE_access_settings-whitelist-rule_idBody"},"responses":{"204":{"description":"","content":{"*/*":{"schema":{"properties":{},"type":"object"}}}}},"security":[{"Authorization":[]}],"summary":"Remove a specific IP from the whitelist","tags":["IP Access Management"]},"get":{"description":"**This endpoint allows you to retreive a specific IP address that has been whitelisted.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).","operationId":"GET_access_settings-whitelist-rule_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the IP was whitelisted.","type":"integer"},"id":{"description":"The ID of the IP address.","type":"integer"},"ip":{"description":"The IP address.","type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the IP address was last updated.","type":"integer"}},"required":["id","ip","created_at","updated_at"],"type":"object"},"examples":{"response":{"value":{"created_at":1441824715,"id":1,"ip":"192.168.1.1","updated_at":1441824715}}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve a specific whitelisted IP","tags":["IP Access Management"]},"parameters":[{"description":"The ID of the whitelisted IP address that you want to retrieve.","in":"path","name":"rule_id","required":true,"schema":{"type":"string"}}]},"/alerts":{"get":{"description":"**This endpoint allows you to retieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).","operationId":"GET_alerts","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/DELETE_access_settings-whitelist-rule_idBody"},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"description":"The list of alerts.","items":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the alert was created.","type":"integer"},"email_to":{"description":"The email address that the alert will be sent to.","type":"string"},"frequency":{"description":"If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\".","type":"string"},"id":{"description":"The ID of the alert.","type":"integer"},"percentage":{"description":"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.","type":"integer"},"type":{"description":"The type of alert.","enum":["usage_limit","stats_notification"],"type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the alert was last modified.","type":"integer"}},"required":["created_at","email_to","id","type"],"type":"object"},"type":"array"},"examples":{"response":{"value":[{"created_at":1451498784,"email_to":"example1@example.com","id":46,"percentage":90,"type":"usage_limit","updated_at":1451498784},{"created_at":1451498812,"email_to":"example2@example.com","frequency":"monthly","id":47,"type":"stats_notification","updated_at":1451498812},{"created_at":1451520930,"email_to":"example3@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451520930}]}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve all alerts","tags":["Alerts"]},"post":{"description":"**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:\n\n* `usage_limit` allows you to set the threshold at which an alert will be sent.\n* `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).","operationId":"POST_alerts","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"}},{"in":"header","name":"on-behalf-of","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"example":{"email_to":"example@example.com","frequency":"daily","type":"stats_notification"},"properties":{"email_to":{"description":"The email address the alert will be sent to.\nExample: test@example.com","nullable":true,"type":"string"},"frequency":{"description":"Required for stats_notification. How frequently the alert will be sent.\nExample: daily","type":"string"},"percentage":{"description":"Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90","type":"integer"},"type":{"description":"The type of alert you want to create. Can be either usage_limit or stats_notification.\nExample: usage_limit","enum":["stats_notification","usage_limit"],"type":"string"}},"required":["type","email_to"],"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the alert was created.","type":"integer"},"email_to":{"description":"The email address that the alert will be sent to.","type":"string"},"frequency":{"description":"If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\".","type":"string"},"id":{"description":"The ID of the alert.","type":"integer"},"percentage":{"description":"\"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.","type":"integer"},"type":{"description":"The type of alert.","type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the alert was last modified.","type":"integer"}},"required":["created_at","email_to","id","type","updated_at"],"type":"object"},"examples":{"response":{"value":{"created_at":1451520930,"email_to":"test@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451520930}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"}}}}},"security":[{"Authorization":[]}],"summary":"Create a new Alert","tags":["Alerts"]}},"/alerts/{alert_id}":{"delete":{"description":"**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).","operationId":"DELETE_alerts-alert_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"description":"","content":{"*/*":{"schema":{"properties":{},"type":"object"}}}}},"security":[{"Authorization":[]}],"summary":"Delete an alert","tags":["Alerts"]},"get":{"description":"**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).","operationId":"GET_alerts-alert_id","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the alert was created.","type":"integer"},"email_to":{"description":"The email address that the alert will be sent to.","type":"string"},"frequency":{"description":"If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\".","type":"string"},"id":{"description":"The ID of the alert.","type":"integer"},"percentage":{"description":"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.","type":"integer"},"type":{"description":"The type of alert.","enum":["usage_alert","stats_notification"],"type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the alert was last modified.","type":"integer"}},"required":["created_at","email_to","id","type","updated_at"],"type":"object"},"examples":{"response":{"value":{"created_at":1451520930,"email_to":"example@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451520930}}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve a specific alert","tags":["Alerts"]},"parameters":[{"description":"The ID of the alert you would like to retrieve.","in":"path","name":"alert_id","required":true,"schema":{"type":"integer"}}],"patch":{"description":"**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).","operationId":"PATCH_alerts-alert_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"email_to":"example@example.com"},"properties":{"email_to":{"description":"The new email address you want your alert to be sent to.\nExample: test@example.com","type":"string"},"frequency":{"description":"The new frequency at which to send the stats_notification alert.\nExample: monthly","type":"string"},"percentage":{"description":"The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90","type":"integer"}},"type":"object"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the alert was created.","type":"integer"},"email_to":{"description":"The email address that the alert will be sent to.","type":"string"},"frequency":{"description":"If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\".","type":"string"},"id":{"description":"The ID of the alert.","type":"integer"},"percentage":{"description":"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.","type":"integer"},"type":{"description":"The type of alert.","enum":["usage_alert","stats_notification"],"type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the alert was last modified.","type":"integer"}},"required":["created_at","email_to","id","type","updated_at"],"type":"object"},"examples":{"response":{"value":{"created_at":1451520930,"email_to":"example@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451522691}}}}}}},"security":[{"Authorization":[]}],"summary":"Update an alert","tags":["Alerts"]}},"/api_keys":{"get":{"description":"**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).","operationId":"GET_api_keys","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"result":{"items":{"$ref":"#/components/schemas/api_key_name_id"},"type":"array"}},"type":"object"},"examples":{"response":{"value":{"result":[{"api_key_id":"some-apikey-id","name":"API Key Name"},{"api_key_id":"another-apikey-id","name":"API Key Name 2"}]}}}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"authorization required"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve all API Keys belonging to the authenticated user","tags":["API Keys"]},"post":{"description":"**This endpoint allows you to create a new random API Key for the user.**\n\nA JSON request body containing a \"name\" property is required. If number of maximum keys is reached, HTTP 403 will be returned.\n\nThere is a limit of 100 API Keys on your account.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\nSee the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.","operationId":"create-api-keys","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"name":"My API Key","sample":"data","scopes":["mail.send","alerts.create","alerts.read"]},"properties":{"name":{"description":"The name you will use to describe this API Key.","type":"string"},"sample":{"type":"string"},"scopes":{"description":"The individual permissions that you are giving to this API Key.","items":{"type":"string"},"type":"array"}},"required":["name"],"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"api_key":{"type":"string"},"api_key_id":{"type":"string"},"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"}},"type":"object"},"examples":{"response":{"value":{"api_key":"SG.xxxxxxxx.yyyyyyyy","api_key_id":"xxxxxxxx","name":"My API Key","scopes":["mail.send","alerts.create","alerts.read"]}}}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"field":"name","message":"missing required argument"}]}}}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"authorization required"}]}}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"Cannot create more than 100 API Keys"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Create API keys","tags":["API Keys"]}},"/api_keys/{api_key_id}":{"delete":{"description":"**This endpoint allows you to revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|","operationId":"DELETE_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"description":"","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"unable to find API Key"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Delete API keys","tags":["API Keys"]},"get":{"description":"**This endpoint allows you to retrieve a single api key.**\n\nIf the API Key ID does not exist an HTTP 404 will be returned.","operationId":"GET_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"result":{"items":{"$ref":"#/components/schemas/api_key_name_id_scopes"},"type":"array"}},"type":"object"},"examples":{"response":{"value":{"result":[{"api_key_id":"some-apikey-id","name":"API Key Name"},{"api_key_id":"another-apikey-id","name":"API Key Name 2"}]}}}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"authorization required"}]}}}}}},"404":{"description":"Unexpected error in API call. See HTTP response body for details.","content":{"application/json":{"schema":{"type":"object"},"examples":{"response":{"value":{"errors":[{"message":"unable to find API Key"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve an existing API Key","tags":["API Keys"]},"parameters":[{"description":"The ID of the API Key for which you are requesting information.","in":"path","name":"api_key_id","required":true,"schema":{"type":"string"}}],"patch":{"description":"**This endpoint allows you to 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":"PATCH_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"name":"A New Hope"},"properties":{"name":{"description":"The new name of the API Key.","type":"string"}},"type":"object"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api_key_name_id"},"examples":{"response":{"value":{"api_key_id":"qfTQ6KG0QBiwWdJ0-pCLCA","name":"A New Hope"}}}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"authorization required"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Update API keys","tags":["API Keys"]},"put":{"description":"**This endpoint allows you to update the name and scopes of a given API key.**\n\nA 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).","operationId":"PUT_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"name":"A New Hope","scopes":["user.profile.read","user.profile.update"]},"properties":{"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/api_key_name_id_scopes"},"examples":{"response":{"value":{"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"expected JSON request body with 'name' property"}]}}}}}},"401":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unexpected error in API call. See HTTP response body for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/global_ErrorResponse"},"examples":{"response":{"value":{"errors":[{"message":"unable to find API Key to update"}]}}}}}}},"security":[{"Authorization":[]}],"summary":"Update the name & scopes of an API Key","tags":["API Keys"]}},"/asm/groups":{"get":{"description":"**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).\n\nSuppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content.","operationId":"GET_asm-groups","parameters":[{"description":"The ID of a suppression group that you want to retrieve information for.","in":"query","name":"id","schema":{"type":"integer"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/suppression_group"},"type":"array"},"examples":{"response":{"value":[{"description":"Our monthly newsletter.","id":100,"is_default":true,"name":"Newsletters","unsubscribes":400},{"description":"Emails triggered by user-defined rules.","id":101,"is_default":false,"name":"Alerts","unsubscribes":1}]}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve information about multiple suppression groups","tags":["Suppressions - Unsubscribe Groups"]},"post":{"description":"**This endpoint allows you to create a new suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.","operationId":"POST_asm-groups","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"description":"Suggestions for products our users might like.","is_default":true,"name":"Product Suggestions"},"properties":{"description":{"description":"A brief description of your new suppression group.","maxLength":100,"type":"string"},"is_default":{"description":"Indicates if you would like this to be your default suppression group.","type":"boolean"},"name":{"description":"The name that you would like to use for your new suppression group.","maxLength":30,"type":"string"}},"required":["name","description"],"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"description":{"description":"A brief description of the suppression group.","type":"string"},"id":{"description":"The ID of the suppression group.","type":"integer"},"is_default":{"description":"Indicates if this is the default suppression group.","type":"boolean"},"name":{"description":"The name of the suppression group.","type":"string"}},"required":["id","name","description","is_default"],"type":"object"},"examples":{"response":{"value":{"description":"Suggestions for products our users might like.","id":103,"is_default":false,"name":"Product Suggestions"}}}}}}},"security":[{"Authorization":[]}],"summary":"Create a new suppression group","tags":["Suppressions - Unsubscribe Groups"]}},"/asm/groups/{group_id}":{"delete":{"description":"**This endpoint allows you to delete a suppression group.**\n\nYou can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the \"one-click unsubscribe\" option on an email associated with a deleted group, that recipient will be added to the global suppression list.\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.","operationId":"DELETE_asm-groups-group_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/DELETE_access_settings-whitelist-rule_idBody"},"responses":{"204":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[{"Authorization":[]}],"summary":"Delete a suppression group.","tags":["Suppressions - Unsubscribe Groups"]},"get":{"description":"**This endpoint allows you to retrieve a single suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.","operationId":"GET_asm-groups-group_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"description":{"description":"The description of the suppression group.","type":"string"},"id":{"description":"The ID of the suppression group.","type":"integer"},"is_default":{"description":"Indicates if this is the default suppression group.","type":"boolean"},"last_email_sent_at":{"description":"A unix timestamp indicating the last time this group was assigned to an email.","nullable":true},"name":{"description":"The name of the suppression group.","type":"string"},"unsubscribes":{"description":"The number of unsubscribes, or suppressions, in this group.","type":"integer"}},"type":"object"},"examples":{"response":{"value":{"description":"Our monthly newsletter.","id":100,"is_default":true,"name":"Newsletters","unsubscribes":400}}}}}}},"security":[{"Authorization":[]}],"summary":"Get information on a single suppression group.","tags":["Suppressions - Unsubscribe Groups"]},"parameters":[{"description":"The ID of the suppression group you would like to retrieve.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"patch":{"description":"**This endpoint allows you to update or change a suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.","operationId":"PATCH_asm-groups-group_id","parameters":[{"$ref":"#/components/parameters/trait_authorizationHeader_Authorization"},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"description":"Suggestions for items our users might like.","id":103,"name":"Item Suggestions"},"properties":{"description":{"description":"The description of the suppression group.","maxLength":100,"type":"string"},"id":{"description":"The id of the suppression group.","type":"integer"},"is_default":{"description":"Indicates if the suppression group is set as the default group.","type":"boolean"},"name":{"description":"The name of the suppression group. Each group created by a user must have a unique name.","maxLength":30,"type":"string"}},"required":["name"],"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/suppression_group"},"examples":{"response":{"value":{"description":"Suggestions for items our users might like.","id":103,"name":"Item Suggestions"}}}}}}},"summary":"Update a suppression group.","tags":["Suppressions - Unsubscribe Groups"]}},"/asm/groups/{group_id}/suppressions":{"get":{"description":"**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.","operationId":"GET_asm-groups-group_id-suppressions","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"description":"The list of email addresses belonging to the given suppression group.","items":{"type":"string"},"type":"array"},"examples":{"response":{"value":["example@example.com","example2@example.com"]}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve all suppressions for a suppression group","tags":["Suppressions - Suppressions"]},"parameters":[{"description":"The id of the unsubscribe group that you are adding suppressions to.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"post":{"description":"**This endpoint allows you to add email addresses to an unsubscribe group.**\n\nIf you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.","operationId":"POST_asm-groups-group_id-suppressions","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"recipient_emails":["test1@example.com","test2@example.com"]},"properties":{"recipient_emails":{"description":"The email address that you want to add to the unsubscribe group.","items":{"type":"string"},"type":"array"}},"required":["recipient_emails"],"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"recipient_emails":{"description":"The email address that were added to the suppressions list.","items":{"type":"string"},"type":"array"}},"required":["recipient_emails"],"type":"object"},"examples":{"response":{"value":{"recipient_emails":["test1@example.com","test2@example.com"]}}}}}}},"security":[{"Authorization":[]}],"summary":"Add suppressions to a suppression group","tags":["Suppressions - Suppressions"]}},"/asm/groups/{group_id}/suppressions/search":{"parameters":[{"description":"The ID of the suppression group that you would like to search.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}}],"post":{"description":"**This endpoint allows you to search a suppression group for multiple suppressions.**\n\nWhen given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).","operationId":"POST_asm-groups-group_id-suppressions-search","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"recipient_emails":["exists1@example.com","exists2@example.com","doesnotexists@example.com"]},"properties":{"recipient_emails":{"description":"The list of email address that you want to search the suppression group for.","items":{"type":"string"},"type":"array"}},"required":["recipient_emails"],"type":"object"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"properties":{"recipient_emails":{"description":"The email address from your search that do exist in the suppression group.","items":{"type":"string"},"type":"array"}},"required":["recipient_emails"],"type":"object"},"examples":{"response":{"value":{"recipient_emails":["exists1@example.com","exists2@example.com"]}}}}}}},"security":[{"Authorization":[]}],"summary":"Search for suppressions within a group","tags":["Suppressions - Suppressions"]}},"/asm/groups/{group_id}/suppressions/{email}":{"delete":{"description":"**This endpoint allows you to remove a suppressed email address from the given suppression group.**\n\nSuppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group.","operationId":"DELETE_asm-groups-group_id-suppressions-email","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/DELETE_access_settings-whitelist-rule_idBody"},"responses":{"204":{"description":"","content":{"*/*":{"schema":{"nullable":true}}}}},"security":[{"Authorization":[]}],"summary":"Delete a suppression from a suppression group","tags":["Suppressions - Suppressions"]},"parameters":[{"description":"The id of the suppression group that you are removing an email address from.","in":"path","name":"group_id","required":true,"schema":{"type":"string"}},{"description":"The email address that you want to remove from the suppression group.","in":"path","name":"email","required":true,"schema":{"type":"string"}}]},"/asm/suppressions":{"get":{"description":"**This endpoint allows you to retrieve a list of all suppressions.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).","operationId":"GET_asm-suppressions","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"items":{"properties":{"created_at":{"description":"A UNIX timestamp indicating when the suppression was created.","type":"integer"},"email":{"description":"The email address that was suppressed.","type":"string"},"group_id":{"description":"The id of the suppression group that this email address belongs to.","type":"integer"},"group_name":{"description":"The name of the suppression group that this email address belongs to.","type":"string"}},"required":["email","group_id","group_name","created_at"],"type":"object"},"type":"array"},"examples":{"response":{"value":[{"created_at":1410986704,"email":"test1@example.com","group_id":1,"group_name":"Weekly News"},{"created_at":1411493671,"email":"test1@example.com","group_id":2,"group_name":"Daily News"},{"created_at":1411493671,"email":"test2@example.com","group_id":2,"group_name":"Daily News"}]}}}}}},"security":[{"Authorization":[]}],"summary":"Retrieve all suppressions","tags":["Suppressions - Suppressions"]}},"/asm/suppressions/global":{"post":{"description":"**This endpoint allows you to add one or more email addresses to the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).","operationId":"POST_asm-suppressions-global","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"recipient_emails":["test1@example.com","test2@example.com"]},"properties":{"recipient_emails":{"description":"The email address, or addresses, that you want to add to the global suppressions group.","items":{"type":"string"},"type":"array"}},"type":"object"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"properties":{"recipient_emails":{"description":"The email addresses that are globally suppressed","items":{"type":"string"},"type":"array"}},"required":["recipient_emails"],"type":"object"},"examples":{"response":{"value":{"recipient_emails":["test1@example.com","test2@example.com"]}}}}}}},"security":[{"Authorization":[]}],"summary":"Add recipient addresses to the global suppression group.","tags":["Suppressions - Global Suppressions"]}},"/asm/suppressions/global/{email}":{"delete":{"description":"**This endpoint allows you to remove an email address from the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).","operationId":"DELETE_asm-suppressions-global-email","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/DELETE_access_settings-whitelist-rule_idBody"},"responses":{"204":{"description":"","content":{"*/*":{"schema":{"type":"object"}}}}},"security":[{"Authorization":[]}],"summary":"Delete a Global Suppression","tags":["Suppressions - Global Suppressions"]},"get":{"description":"**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the res