openapi-directory/api/sendgrid.com.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","servers":[{"url":"http://api.sendgrid.com/v3"}],"info":{"description":"The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data. The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data.","title":"Email Activity (beta)","version":"1.0.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":"openapi","url":"https://raw.githubusercontent.com/sendgrid/sendgrid-oai/main/oai.json","version":"3.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.**","operationId":"GET_access_settings-activity","parameters":[{"description":"Limits the number of IPs to return.","in":"query","name":"limit","schema":{"default":20,"type":"integer"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"result":[{"allowed":false,"auth_method":"Web","first_at":1444087966,"ip":"1.1.1.1","last_at":1444406672,"location":"Australia"},{"allowed":false,"auth_method":"Web","first_at":1444087505,"ip":"1.2.3.48","last_at":1444087505,"location":"Mukilteo, Washington"}]}}},"schema":{"properties":{"result":{"description":"An array containing the IPs that recently attempted to access your account.","items":{"properties":{"allowed":{"description":"Indicates if the IP address was granted access to the account.","type":"boolean"},"auth_method":{"description":"The authentication method used when attempting access.","type":"string"},"first_at":{"description":"A Unix timestamp indicating when the first access attempt was made.","type":"integer"},"ip":{"description":"The IP addressed used during the access attempt.","type":"string"},"last_at":{"description":"A Unix timestamp indicating when the most recent access attempt was made","type":"integer"},"location":{"description":"The geographic location from which the access attempt originated.","type":"string"}},"required":["allowed","auth_method","first_at","ip","last_at","location"],"type":"object"},"type":"array"}},"required":["result"],"type":"object"}}},"description":""},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"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 IP addresses from your list of allowed addresses.**\n\nTo remove one or more IP addresses, pass this endpoint an array containing the ID(s) associated with the IP(s) you intend to remove. You can retrieve the IDs associated with your allowed IP addresses using the \"Retrieve a list of currently allowed IPs\" endpoint.\n\nIt is possible to remove your own IP address, which will block access to your account. You will need to submit a [support ticket](https://sendgrid.com/docs/ui/account-and-settings/support/) if this happens. For this reason, it is important to double check that you are removing only the IPs you intend to remove when using this endpoint.","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 allow list.","items":{"type":"integer"},"type":"array"}},"type":"object"}}}},"responses":{"204":{"content":{"application/json":{"schema":{"properties":{},"type":"object"}}},"description":""},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Remove one or more IPs from the allow list","tags":["IP Access Management"]},"get":{"description":"**This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.**\n\nEach IP address returned to you will have `created_at` and `updated_at` dates. Each IP will also be associated with an `id` that can be used to remove the address from your allow list.","operationId":"GET_access_settings-whitelist","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"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}]}}},"schema":{"$ref":"#/components/schemas/ip-access-response"}}},"description":""},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Retrieve a list of currently allowed IPs","tags":["IP Access Management"]},"post":{"description":"**This endpoint allows you to add one or more allowed IP addresses.**\n\nTo allow one or more IP addresses, pass them to this endpoint in an array. Once an IP address is added to your allow list, it will be assigned an `id` that can be used to remove the address. You can retrieve the ID associated with an IP using the \"Retrieve a list of currently allowed IPs\" endpoint.","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 allow.","items":{"properties":{"ip":{"description":"An IP address that you want to allow.","type":"string"}},"required":["ip"],"type":"object"},"type":"array"}},"required":["ips"],"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"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}]}}},"schema":{"$ref":"#/components/schemas/ip-access-response"}}},"description":""},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Add one or more IPs to the allow list","tags":["IP Access Management"]}},"/access_settings/whitelist/{rule_id}":{"delete":{"description":"**This endpoint allows you to remove a specific IP address from your list of allowed addresses.**\n\nWhen removing a specific IP address from your list, you must include the ID in your call.  You can retrieve the IDs associated with your allowed IP addresses using the \"Retrieve a list of currently allowed IPs\" endpoint.","operationId":"DELETE_access_settings-whitelist-rule_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"content":{"application/json":{"schema":{"properties":{},"type":"object"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Remove a specific IP from the allowed list","tags":["IP Access Management"]},"get":{"description":"**This endpoint allows you to retreive a specific IP address that has been allowed to access your account.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call. You can retrieve the IDs associated with your allowed IP addresses using the \"Retrieve a  list of currently allowed IPs\" endpoint.","operationId":"GET_access_settings-whitelist-rule_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"created_at":1441824715,"id":1,"ip":"192.168.1.1","updated_at":1441824715}}},"schema":{"$ref":"#/components/schemas/ip-access-response"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Retrieve a specific allowed IP","tags":["IP Access Management"]},"parameters":[{"description":"The ID of the allowed 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 retrieve 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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).","operationId":"GET_alerts","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"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}]}},"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"}}},"description":""}},"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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).","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","format":"email","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":{"content":{"application/json":{"examples":{"response":{"value":{"created_at":1451520930,"email_to":"test@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451520930}}},"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.","format":"email","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"}}},"description":""},"400":{"content":{"application/json":{"schema":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"}}},"description":""}},"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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).","operationId":"DELETE_alerts-alert_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"content":{"application/json":{"schema":{"properties":{},"type":"object"}}},"description":""}},"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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).","operationId":"GET_alerts-alert_id","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"created_at":1451520930,"email_to":"example@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451520930}}},"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"}}},"description":""}},"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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).","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":{"content":{"application/json":{"examples":{"response":{"value":{"created_at":1451520930,"email_to":"example@example.com","frequency":"daily","id":48,"type":"stats_notification","updated_at":1451522691}}},"schema":{"properties":{"created_at":{"description":"A Unix timestamp indicating when the alert was created.","type":"integer"},"email_to":{"description":"The email address that the alert will be sent to.","type":"string"},"frequency":{"description":"If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\".","type":"string"},"id":{"description":"The ID of the alert.","type":"integer"},"percentage":{"description":"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.","type":"integer"},"type":{"description":"The type of alert.","enum":["usage_alert","stats_notification"],"type":"string"},"updated_at":{"description":"A Unix timestamp indicating when the alert was last modified.","type":"integer"}},"required":["created_at","email_to","id","type","updated_at"],"type":"object"}}},"description":""}},"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\nA successful response from this API will include all available API keys' names and IDs.\n\nFor security reasons, there is not a way to retrieve the key itself after it's created. If you lose your API key, you must create a new one. Only the \"Create API keys\" endpoint will return a key to you and only at the time of creation.\n\nAn `api_key_id` can be used to update or delete the key, as well as retrieve the key's details, such as its scopes.","operationId":"GET_api_keys","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"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"}]}}},"schema":{"properties":{"result":{"items":{"$ref":"#/components/schemas/api_key_name_id"},"type":"array"}},"type":"object"}}},"description":""},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"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 API Key for the user.**\n\nTo create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.\n\n> There is a limit of 100 API Keys on your account.\n\nA JSON request body containing a `name` property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a `403` status will be returned.\n\nThough the `name` field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body.\n\nIt is not necessary to pass a `scopes` field to the API when creating a key, but you should be aware that omitting the `scopes` field from your request will create a key with \"Full Access\" permissions by default.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.","operationId":"create-api-keys","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"name":"My API Key","scopes":["mail.send","alerts.create","alerts.read"]},"properties":{"name":{"description":"The name you will use to describe this API Key.","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":{"content":{"application/json":{"examples":{"response":{"value":{"api_key":"SG.xxxxxxxx.yyyyyyyy","api_key_id":"xxxxxxxx","name":"My API Key","scopes":["mail.send","alerts.create","alerts.read"]}}},"schema":{"properties":{"api_key":{"type":"string"},"api_key_id":{"type":"string"},"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"}},"type":"object"}}},"description":""},"400":{"$ref":"#/components/responses/trait_apiKeysErrors_400"},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_apiKeysErrors_403"},"404":{"$ref":"#/components/responses/trait_apiKeysErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"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 using an `api_key_id`**\n\nAuthentications using a revoked API Key will fail after after some small propogation delay. If the API Key ID does not exist, a `404` status will be returned.","operationId":"DELETE_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"description":""},"400":{"$ref":"#/components/responses/trait_apiKeysErrors_400"},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Delete API keys","tags":["API Keys"]},"get":{"description":"**This endpoint allows you to retrieve a single API key using an `api_key_id`.**\n\nThe endpoint will return a key's name, ID, and scopes. If the API Key ID does not, exist a `404` status will be returned.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.","operationId":"GET_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"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"}]}}},"schema":{"properties":{"result":{"items":{"$ref":"#/components/schemas/api_key_name_id_scopes"},"type":"array"}},"type":"object"}}},"description":""},"400":{"$ref":"#/components/responses/trait_apiKeysErrors_400"},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_apiKeysErrors_403"},"404":{"$ref":"#/components/responses/trait_apiKeysErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Retrieve an existing API Key","tags":["API Keys"]},"parameters":[{"description":"","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\nYou must pass this endpoint a JSON request body with a `name` property, which will be used to rename the key associated with the `api_key_id` passed in the URL.","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"}},"required":["name"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"api_key_id":"qfTQ6KG0QBiwWdJ0-pCLCA","name":"A New Hope"}}},"schema":{"$ref":"#/components/schemas/api_key_name_id"}}},"description":""},"400":{"$ref":"#/components/responses/trait_apiKeysErrors_400"},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Update API key name","tags":["API Keys"]},"put":{"description":"**This endpoint allows you to update the name and scopes of a given API key.**\n\nYou must pass this endpoint a JSON request body with a `name` field and a `scopes` array containing at least one scope. The `name` and `scopes` fields will be used to update the key associated with the `api_key_id` in the request URL.\n\nIf you need to update a key's scopes only, pass the `name` field with the key's existing name; the `name` will not be modified. If you need to update a key's name only, use the \"Update API key name\" endpoint.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes.","operationId":"PUT_api_keys-api_key_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"example":{"name":"Profiles key","scopes":["user.profile.read","user.profile.update"]},"properties":{"name":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array"}},"required":["name"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"api_key_id":"qfTQ6KG0QBiwWdJ0-pCLCA","name":"Profiles Key","scopes":["user.profile.read","user.profile.update"]}}},"schema":{"$ref":"#/components/schemas/api_key_name_id_scopes"}}},"description":""},"400":{"$ref":"#/components/responses/trait_apiKeysErrors_400"},"401":{"$ref":"#/components/responses/trait_globalErrors_401"},"403":{"$ref":"#/components/responses/trait_globalErrors_403"},"404":{"$ref":"#/components/responses/trait_globalErrors_404"},"500":{"$ref":"#/components/responses/trait_globalErrors_500"}},"security":[{"Authorization":[]}],"summary":"Update API key name and scopes","tags":["API Keys"]}},"/asm/groups":{"get":{"description":"**This endpoint allows you to retrieve a list of all suppression groups created by this user.**\n\nThis endpoint can also return information for multiple group IDs that you include in your request. To add a group ID to your request, simply append `?id=123456&id=123456`, with the appropriate group IDs.","operationId":"GET_asm-groups","parameters":[{"in":"query","name":"id","schema":{"type":"integer"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":[{"description":"An Unsubscribe Group","id":1234,"is_default":true,"last_email_sent_at":null,"name":"Unsubscribe Group","unsubscribes":1234},{"description":"An Unsubscribe Group","id":1234,"is_default":true,"last_email_sent_at":null,"name":"Unsubscribe Group","unsubscribes":1234}]}},"schema":{"items":{"$ref":"#/components/schemas/suppression_group"},"type":"array"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Retrieve all suppression groups associated with the user.","tags":["Suppressions - Unsubscribe Groups"]},"post":{"description":"**This endpoint allows you to create a new suppression group.**\n\nTo add an email address to the suppression group, [create a Suppression](https://sendgrid.api-docs.io/v3.0/suppressions-suppressions/add-suppressions-to-a-suppression-group).","operationId":"POST_asm-groups","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/suppression-group-request-base"}}}},"responses":{"201":{"content":{"application/json":{"examples":{"response":{"value":{"description":"Suggestions for products our users might like.","id":103,"is_default":false,"name":"Product Suggestions"}}},"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"}}},"description":""}},"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\nIf 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\nDeleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.","operationId":"DELETE_asm-groups-group_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"content":{"application/json":{"schema":{"type":"object"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Delete a Suppression Group","tags":["Suppressions - Unsubscribe Groups"]},"get":{"description":"**This endpoint allows you to retrieve a single suppression group.**","operationId":"GET_asm-groups-group_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"description":"Our monthly newsletter.","id":100,"is_default":true,"last_email_sent_at":null,"name":"Newsletters","unsubscribes":400}}},"schema":{"allOf":[{"$ref":"#/components/schemas/suppression-group-request-base"},{"properties":{"id":{"description":"The ID of the suppression group.","type":"integer"},"last_email_sent_at":{"nullable":true,"type":"string"},"unsubscribes":{"description":"The number of unsubscribes, or suppressions, in this group.","type":"integer"}},"required":["id"],"type":"object"}]}}},"description":""}},"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.**","operationId":"PATCH_asm-groups-group_id","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/suppression-group-request-base"}],"example":{"description":"Suggestions for items our users might like.","id":103,"name":"Item Suggestions"}}}}},"responses":{"201":{"content":{"application/json":{"examples":{"response":{"value":{"description":"Suggestions for items our users might like.","id":103,"name":"Item Suggestions"}}},"schema":{"$ref":"#/components/schemas/suppression_group"}}},"description":""}},"security":[{"Authorization":[]}],"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.**","operationId":"GET_asm-groups-group_id-suppressions","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":["example@example.com","example2@example.com"]}},"schema":{"description":"The list of email addresses belonging to the given suppression group.","items":{"format":"email","type":"string"},"type":"array"}}},"description":""}},"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.","operationId":"POST_asm-groups-group_id-suppressions","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/suppressions-request"},"responses":{"201":{"content":{"application/json":{"examples":{"response":{"value":{"recipient_emails":["test1@example.com","test2@example.com"]}}},"schema":{"properties":{"recipient_emails":{"description":"The email addresses you added to the unsubscribe group","items":{"format":"email","type":"string"},"type":"array"}},"type":"object"}}},"description":""}},"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 only return the email addresses that have been unsubscribed from the given group.","operationId":"POST_asm-groups-group_id-suppressions-search","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/suppressions-request"},"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":["exists1@example.com","exists2@example.com"]}},"schema":{"description":"The email address from your search that do exist in the suppression group.","items":{"format":"email","type":"string"},"type":"array"}}},"description":""}},"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\nRemoving an address will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.","operationId":"DELETE_asm-groups-group_id-suppressions-email","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"content":{"application/json":{"schema":{"nullable":true}}},"description":""}},"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.**","operationId":"GET_asm-suppressions","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"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"}]}},"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"}}},"description":""}},"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.**","operationId":"POST_asm-suppressions-global","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"requestBody":{"$ref":"#/components/requestBodies/suppressions-request"},"responses":{"201":{"content":{"application/json":{"examples":{"response":{"value":{"recipient_emails":["test1@example.com","test2@example.com"]}}},"schema":{"properties":{"recipient_emails":{"description":"The email addresses that are globally suppressed","items":{"format":"email","type":"string"},"type":"array"}},"required":["recipient_emails"],"type":"object"}}},"description":""}},"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\nDeleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.","operationId":"DELETE_asm-suppressions-global-email","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"204":{"content":{"application/json":{"schema":{"type":"object"}}},"description":""}},"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 already globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.","operationId":"GET_asm-suppressions-global-email","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"recipient_email":"test@example.com"}}},"schema":{"properties":{"recipient_email":{"description":"The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed.","format":"email","type":"string"}},"required":["recipient_email"],"title":"Retrieve a Global Suppression response","type":"object"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Retrieve a Global Suppression","tags":["Suppressions - Global Suppressions"]},"parameters":[{"description":"The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.","in":"path","name":"email","required":true,"schema":{"type":"string"}}]},"/asm/suppressions/{email}":{"get":{"description":"**This endpoint returns a list of all groups from which the given email address has been unsubscribed.**","operationId":"GET_asm-suppressions-email","parameters":[{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"suppressions":[{"description":"Optional description.","id":1,"is_default":true,"name":"Weekly News","suppressed":true},{"description":"Some daily news.","id":2,"is_default":true,"name":"Daily News","suppressed":true},{"description":"An old group.","id":2,"is_default":false,"name":"Old News","suppressed":false}]}}},"schema":{"properties":{"suppressions":{"description":"The array of suppression groups.","items":{"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 the suppression group  is set as the default.","type":"boolean"},"name":{"description":"The name of the suppression group.","type":"string"},"suppressed":{"description":"Indicates if the given email address is suppressed for this group.","type":"boolean"}},"required":["description","id","is_default","name","suppressed"],"type":"object"},"type":"array"}},"required":["suppressions"],"type":"object"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Retrieve all suppression groups for an email address","tags":["Suppressions - Suppressions"]},"parameters":[{"description":"The email address that you want to search suppression groups for.","in":"path","name":"email","required":true,"schema":{"type":"string"}}]},"/browsers/stats":{"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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).","operationId":"GET_browsers-stats","parameters":[{"description":"The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.","in":"query","name":"browsers","schema":{"type":"string"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"},{"$ref":"#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_limit"},{"$ref":"#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_offset"},{"$ref":"#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_aggregated_by"},{"$ref":"#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_start_date"},{"$ref":"#/components/parameters/trait_statsAdvancedQueryStringsLimitOffset_end_date"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":[{"date":"2025-06-15T13:49:25.347Z","stats":[{"metrics":{"clicks":0,"unique_clicks":0},"name":"Chrome","type":"browser"},{"metrics":{"clicks":1,"unique_clicks":1},"name":"Firefox","type":"browser"}]},{"date":"2025-06-15T13:49:25.347Z","stats":[{"metrics":{"clicks":0,"unique_clicks":0},"name":"Chrome","type":"browser"},{"metrics":{"clicks":1,"unique_clicks":1},"name":"Firefox","type":"browser"}]}]}},"schema":{"items":{"properties":{"date":{"description":"The date that the statistics were gathered.","type":"string"},"stats":{"description":"The list of statistics.","items":{"properties":{"metrics":{"$ref":"#/components/schemas/advanced_stats_clicks"},"name":{"description":"The name of the specific segmentation.","type":"string"},"type":{"description":"The type of segmentation.","type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"type":"array"}}},"description":""}},"security":[{"Authorization":[]}],"summary":"Retrieve email statistics by browser.","tags":["Stats"]}},"/campaigns":{"get":{"description":"**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.","operationId":"GET_campaigns","parameters":[{"description":"The number of results you would like to receive at a time.","in":"query","name":"limit","schema":{"default":10,"type":"integer"}},{"description":"The index of the first campaign to return, where 0 is the first campaign.","in":"query","name":"offset","schema":{"default":0,"type":"integer"}},{"$ref":"#/components/parameters/trait_onBehalfOfSubuser_on-behalf-of"}],"responses":{"200":{"content":{"application/json":{"examples":{"response":{"value":{"result":[{"categories":["spring line"],"custom_unsubscribe_url":"","html_content":"<html><head><title></title></hea